diff --git a/.gitignore b/.gitignore
index 4f8a78e..751c5e6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,7 +14,7 @@ wheels/
 .venv/
 
 # Onshape export intermediates (transient; the committed urdf/<robot>.urdf hub
-# is what --from-cache reuses).
+# is what the generator reuses instead of re-exporting).
 robots/*/cad/assets/
 robots/*/cad/robot.pkl
 
diff --git a/README.md b/README.md
index c6a8d94..bd3b4eb 100644
--- a/README.md
+++ b/README.md
@@ -4,43 +4,62 @@
 [![ROS 2](https://img.shields.io/badge/ROS_2-Jazzy-22314E.svg)](https://docs.ros.org/en/jazzy/)
 [![License](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
 
-Robot description for the **Berkeley Humanoid Lite V2** — a low-cost, open-source 
-humanoid built on [Robstride](https://robstride.com) actuators. This repository is the
-single source of truth for the robot's geometry: it holds the **URDF**, **MJCF**, and
-**xacro** (with a `ros2_control` block) descriptions and meshes, all generated from the
-Onshape CAD.
+Robot description for the Berkeley Humanoid Lite V2, an open-source humanoid built on
+[Robstride](https://robstride.com) actuators. This repository is the single source of
+truth for the robot's geometry. It holds the URDF, MJCF and xacro descriptions and the
+meshes, all generated from the Onshape CAD.
 
 <!-- TODO: add a render / photo of the Lite robot here. -->
 
 The same source serves both worlds:
 
-- **Simulation / RL** — Mujoco Lab and Isaac Lab, via the `robot_assets` Python loader.
-- **ROS 2** — `ros2_control` + `robot_state_publisher`, as the `lite_description`
+- Simulation and RL, through the `robot_assets` Python loader, for Mujoco Lab and Isaac Lab.
+- ROS 2, through `ros2_control` and `robot_state_publisher`, as the `lite_description`
   ament package.
 
 ## Variants
 
 | Variant | Description | DoF | Root | `ros2_control` |
 |---|---|---|---|---|
-| `lite` | full-body Lite humanoid (legs, 1-DoF waist yaw, arms, neck, 5-finger hands) | 72 | `pelvis` | model-only |
-| `lite_pro` | full-body Lite **Pro** humanoid (legs, 3-DoF waist, arms, neck, 5-finger hands) | 74 | `pelvis` | model-only |
-| `lite_dummy` | V1 bimanual upper body (arms + neck) — the configuration `Humanoid Control` deploys | 17 | `chest` | yes — Robstride on two CAN buses |
-| `lite_bimanual` | V2 bimanual arms (no neck) | 14 | `chest` | yes — Robstride on two CAN buses |
-| `lite_biped` | V2 legs (hip ×3 / knee / ankle ×3 per leg) | 14 | `pelvis` | model-only |
+| `lite` | full body (legs, 1-DoF waist yaw, arms, neck, 5-finger hands) | 72 | `pelvis` | model-only |
+| `lite_pro` | full body **Pro** (legs, 3-DoF waist, arms, neck, 5-finger hands) | 74 | `pelvis` | model-only |
+| `lite_dummy` | V1 bimanual upper body (arms + neck), the configuration `Humanoid Control` deploys | 17 | `chest` | Robstride on two CAN buses |
+| `lite_bimanual` | V2 bimanual arms, no neck | 14 | `chest` | Robstride on two CAN buses |
+| `lite_biped` | V2 legs (hip x3, knee, ankle x3 per leg), floating base | 14 | `pelvis` | Robstride on two CAN buses + base IMU |
+| `lite_biped_debug` | `lite_biped` with the flat debug foot instead of the rockered sole | 14 | `pelvis` | Robstride on two CAN buses + base IMU |
 
-All variants are generated from the same Onshape document (different `Configuration=…`); the
-`<robot>.urdf.xacro` of a `ros2_control` variant selects sim / mock / real hardware via xacro args.
+Every variant comes from the same Onshape document with a different `Configuration=`.
+
+## Hardware backends
+
+A variant with a `ros2_control` block selects its backend through two xacro args, the
+convention the [Universal Robots description](https://github.com/UniversalRobots/Universal_Robots_ROS2_Description/blob/ros2/urdf/ur.ros2_control.xacro)
+uses: one boolean per non-real backend, with real hardware as the fallback.
+
+| `sim_mujoco` | `use_mock_hardware` | Backend |
+|---|---|---|
+| `false` | `false` | `humanoid_devices_robstride/RobstrideSystem`, one block per CAN bus |
+| `false` | `true` | `mock_components/GenericSystem` |
+| `true` | any | `mujoco_ros2_control/MujocoSystem` |
+
+`sim_mujoco` wins over `use_mock_hardware`. Note that `sim_mujoco` is unrelated to the
+`use_sim_time` node parameter, which controls the clock.
+
+The switches choose a plugin and nothing else. The joint macros are backend-agnostic and
+always emit their hardware params, because every backend ignores the params it does not
+know. Real hardware needs one `<ros2_control>` block per physical CAN bus, so the real
+path emits several blocks while the mock and MuJoCo paths share one combined block.
 
 ## CAD source
 
 Every description is generated from an Onshape assembly (document
-`e9ee61a2e2678af2088d9f31`) by the `robot_assets` tool — see
-[Re-generating from CAD](#re-generating-from-cad). The files under `robots/<variant>/`
-are build artifacts: **do not hand-edit them**; change the `cad/` inputs and regenerate.
+`e9ee61a2e2678af2088d9f31`) by the `robot_assets` tool. See
+[Re-generating from CAD](#re-generating-from-cad). The files under `robots/<variant>/` are
+build artifacts. Do not hand-edit them. Change the `cad/` inputs and regenerate.
 
 ## Usage
 
-### Simulation / RL (Python, no ROS toolchain)
+### Simulation and RL (Python, no ROS toolchain)
 
 ```bash
 uv add git+https://github.com/Berkeley-Humanoids/Lite-Description.git
@@ -53,48 +72,49 @@ urdf_path = load("robots/lite/urdf/lite.urdf")               # Isaac Lab
 mjcf_path = load("robots/lite_dummy/mjcf/lite_dummy.xml")    # MuJoCo
 ```
 
-`load()` fetches and caches the requested variant's subtree from this GitHub repo; no ROS
-install required.
+`load()` fetches the requested variant's subtree from this GitHub repo and caches it. No
+ROS install is required.
 
 ### ROS 2
 
-`lite_description` is a standard `ament_cmake` package (its `package.xml` is at the repo
-root). Build it in a ROS 2 workspace — or pull it via `vcs` / `humanoid_control.repos` from `Humanoid Control`
-— and `colcon build`. Downstream, `robot_state_publisher` runs xacro on
+`lite_description` is a standard `ament_cmake` package whose `package.xml` sits at the
+repo root. Build it in a ROS 2 workspace, or pull it with `vcs` or
+`humanoid_control.repos` from `Humanoid Control`, then run `colcon build`. Downstream,
+`robot_state_publisher` runs xacro on
 `robots/<variant>/xacro/<variant>.urdf.xacro`, and
 `package://lite_description/robots/<variant>/meshes/visual/...` resolves after install.
-The `<ros2_control>` block selects the hardware backend via xacro args
-(`use_sim` / `use_fake_hardware`), following the `franka_ros2` / Universal Robots
-convention.
 
 ## Repository layout
 
 ```
-Lite-Description/                 # repo root == ament package "lite_description"
+Lite-Description/                  # repo root == ament package "lite_description"
   package.xml  CMakeLists.txt      # ament (colcon); installs robots/<variant>/...
   pyproject.toml                   # pip/uv: builds the robot_assets Python module
-  robot_assets/                    # Python module: the CAD->assets generator + load()
+  robot_assets/                    # Python module: load() and the CAD->assets generator
+    actuators/                     #   actuator spec tables (velocity/effort/armature)
+    workflow/                      #   the generator stages
   robots/                          # per-variant assets (franka_description-style subdir)
     <variant>/
       xacro/                       #   ROS entry (GENERATED)
-        <variant>.urdf.xacro       #     top assembly: args + includes + instantiation
-        <variant>.description.xacro #    <xacro:macro> model: kinematics, ${mesh_root}, base_link
-        <variant>.ros2_control.xacro #   hardware macros: sim / mock / real, MIT interfaces, CAN ids
-      urdf/<variant>.urdf          #   flat URDF (GENERATED; the kinematic HUB; base_link-free)
+        <variant>.urdf.xacro       #     assembly: args, includes, instantiation
+        <variant>.description.xacro  #   model macro: kinematics, ${mesh_root}, base_link
+        <variant>.ros2_control.xacro #   hardware macros: joints, groups, backends
+      urdf/<variant>.urdf          #   flat URDF (GENERATED; the kinematic HUB)
       mjcf/<variant>.xml           #   MJCF (GENERATED; MuJoCo training + deployment sim)
       meshes/visual/*.stl          #   one shared mesh copy
       cad/                         #   generation INPUTS (not installed):
         config.json                #     Onshape document + export options
         joint_properties.json      #     sim tuning: armature / friction / effort_limit
-        physics.json               #     MJCF <option> (optional; deployment-sim tuning)
-        ros2_control.json          #     ROS hardware map (optional; CAN ids / models / buses / modes)
+        physics.json               #     MJCF <option>, freejoint, IMU, contact (optional)
+        ros2_control.json          #     ROS hardware map (optional)
         scad/                      #     collider sources
 ```
 
-The committed `urdf/<variant>.urdf` is the single kinematic hub: the `mjcf` and `xacro`
-stages both derive from it, so the three formats cannot drift. It is `base_link`-free
-(`base_link` is a ROS/KDL concern injected only into the description xacro), which keeps
-the finalize stage idempotent and the MJCF rooted at the CAD root link.
+The committed `urdf/<variant>.urdf` is the single kinematic hub. The `mjcf` and `xacro`
+stages both derive from it, so the three formats cannot drift apart. The hub is
+`base_link`-free, because `base_link` is a ROS and KDL concern that belongs only in the
+description xacro. That keeps the finalize stage idempotent and the MJCF rooted at the CAD
+root link.
 
 ## Re-generating from CAD
 
@@ -106,30 +126,32 @@ sudo apt install openscad        # for collider editing (onshape-to-robot)
 One command produces all three formats from a variant's `cad/` inputs:
 
 ```bash
-# Full pipeline (Onshape -> URDF + MJCF + xacro). Auto-skips the Onshape stage
-# when a committed urdf/<variant>.urdf hub is already present.
+# Full pipeline. The Onshape stage is skipped whenever the URDF hub is committed.
 uv run robot-assets-generate lite_dummy
 
-# Skip the (expensive, ~1000-request) Onshape export and reuse the committed URDF hub:
-uv run robot-assets-generate lite_dummy --from-cache
-
-# Re-emit only some stages after editing physics.json / ros2_control.json:
+# Re-emit only some stages, after editing physics.json or ros2_control.json:
 uv run robot-assets-generate lite_dummy --only mjcf,xacro
-```
 
-Stages (the committed flat `urdf/<variant>.urdf` is the hub; MJCF and xacro both derive
-from it, so the three formats share one kinematic origin):
+# Re-run the Onshape export even though the hub is committed:
+uv run robot-assets-generate lite_dummy --force
+```
 
 | Stage | Reads | Writes |
 |---|---|---|
 | `onshape` | `cad/config.json`, `cad/scad/` | `urdf/<variant>.urdf`, `meshes/visual/` |
-| `urdf` | `urdf/<variant>.urdf`, `joint_properties.json` | finalized `urdf/<variant>.urdf` (effort harmonised; base_link-free; idempotent) |
-| `mjcf` | `urdf/<variant>.urdf`, `joint_properties.json`, `physics.json` | `mjcf/<variant>.xml` (`<option>`, actuators; no `<sensor>` block — joint state is read from sim data, and `mujoco_ros2_control` aborts on non-site sensors) |
+| `urdf` | `urdf/<variant>.urdf`, `joint_properties.json` | finalized `urdf/<variant>.urdf` (welded, effort harmonised, idempotent) |
+| `mjcf` | `urdf/<variant>.urdf`, `joint_properties.json`, `physics.json` | `mjcf/<variant>.xml` |
 | `xacro` | `urdf/<variant>.urdf`, `ros2_control.json` | `xacro/<variant>.*.xacro` (`base_link` injected here) |
 | `package` | — | registers the variant in the repo-root `CMakeLists.txt` |
 
-A variant without a `ros2_control.json` (`lite`, `lite_biped`) generates a **model-only**
-package: a description macro + a thin assembly, no `<ros2_control>`.
+The Onshape stage costs about 1000 API requests, which is why it is skipped by default.
+
+A variant without a `ros2_control.json` generates a model-only package: a description
+macro and a thin assembly, with no `<ros2_control>` block.
+
+The MJCF carries actuators but no `<sensor>` block unless `physics.json` asks for the base
+IMU. Joint state is read from the sim data, and `mujoco_ros2_control` aborts on a sensor
+that is not backed by a `<site>`.
 
 ### Editing colliders (OpenSCAD)
 
@@ -142,14 +164,10 @@ uv run onshape-to-robot-edit-shape ./chest.stl
 ## Tests
 
 ```bash
-uv run pytest        # left/right symmetry, URDF<->MJCF parity, inertial plausibility,
-                     # mesh existence, xacro well-formedness, generator-determinism
+uv run pytest
 ```
 
-The `xacro` + `check_urdf` expansion checks run only where those tools are installed
-(ROS / RoboStack-pixi); they are skipped in the plain `uv` environment and exercised by
-the ROS CI job.
-
-## License
-
-MIT — see [LICENSE](LICENSE).
+The suite covers left/right symmetry, URDF-to-MJCF parity, inertial plausibility, mesh
+existence, xacro well-formedness and generator determinism. The `xacro` and `check_urdf`
+expansion checks run only where those tools are installed, so they are skipped in the
+plain `uv` environment and are exercised by the ROS CI job instead.
diff --git a/package.xml b/package.xml
index d0efa38..79d4e04 100644
--- a/package.xml
+++ b/package.xml
@@ -4,16 +4,19 @@
   <name>lite_description</name>
   <version>0.0.1</version>
   <description>
-    Description package for the Berkeley-Humanoids Lite humanoid (variants under
-    robots/: `lite` full-body and `lite_dummy` bimanual). Each ships xacro (ROS
-    entry, incl. a generated &lt;ros2_control&gt; block), a flattened URDF and MJCF
-    (training / deployment sim), and meshes. All artifacts are generated from
-    Onshape CAD by the `robot_assets` Python tool; do not hand-edit them.
-    ros2_control hardware plugins
-    (mock / mujoco_ros2_control / humanoid_devices_robstride) are referenced by pluginlib
-    string only and are NOT build/exec dependencies of this package. This is an
-    asset-only package: it ships no launch files or RViz configs (visualization
-    and bringup are consumer concerns).
+    Description package for the Berkeley-Humanoids Lite humanoid. Each variant under
+    robots/ (full-body `lite` and `lite_pro`, bimanual `lite_dummy` and `lite_bimanual`,
+    biped `lite_biped` and `lite_biped_debug`) ships xacro as the ROS entry point,
+    including a generated &lt;ros2_control&gt; block, plus a flattened URDF, an MJCF for
+    the training and deployment sim, and meshes. The `robot_assets` Python tool generates
+    every artifact from Onshape CAD, so do not hand-edit them.
+
+    The ros2_control hardware plugins (mock_components, mujoco_ros2_control,
+    humanoid_devices_robstride) are referenced by pluginlib string only. They are not
+    build or exec dependencies of this package.
+
+    This is an asset-only package. It ships no launch files and no RViz configs, because
+    visualization and bringup are consumer concerns.
   </description>
   <maintainer email="chiyufeng@berkeley.edu">Humanoid Control Dev</maintainer>
   <license>MIT</license>
diff --git a/pyproject.toml b/pyproject.toml
index b593a49..01f905a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "robot-assets"
-version = "0.3.1"
+version = "0.4.0"
 description = "Robot asset tool: generate URDF / MJCF / xacro from Onshape CAD, and load robot descriptions"
 readme = "README.md"
 requires-python = ">=3.10"
diff --git a/robot_assets/actuators/func.py b/robot_assets/actuators/func.py
index d746e76..448140f 100644
--- a/robot_assets/actuators/func.py
+++ b/robot_assets/actuators/func.py
@@ -1,41 +1,58 @@
-"""
-Functions to compute actuator parameters.
+"""Compute actuator parameters from a second-order model of the joint.
 
-These equations are derived from:
-BeyondMimic: From Motion Tracking to Versatile Humanoid Control via Guided Diffusion, https://arxiv.org/abs/2508.08241
+The equations come from BeyondMimic: From Motion Tracking to Versatile Humanoid Control
+via Guided Diffusion (https://arxiv.org/abs/2508.08241). Each function takes one of the
+actuator spec tables in this package, such as ``ROBSTRIDE_06_ACTUATOR_PARAMS``.
 """
 
 from math import pi
 
+# Default closed-loop natural frequency, 10 Hz in rad/s.
+NATURAL_FREQUENCY = 10 * 2 * pi
+
 
-def compute_stiffness(actuator_params: dict[str, float], natural_frequency: float = 10 * 2 * pi) -> float:
-    """Compute the stiffness of an actuator.
+def compute_stiffness(
+    actuator_params: dict[str, float],
+    natural_frequency: float = NATURAL_FREQUENCY,
+) -> float:
+    """Return the joint stiffness in Nm/rad.
 
     Args:
-        actuator_params: The parameters of the actuator.
-        natural_frequency: The natural frequency of the actuator in rad/s.
+        actuator_params: An actuator spec table. Reads ``armature`` in kg m^2.
+        natural_frequency: Closed-loop natural frequency in rad/s.
     """
     return actuator_params["armature"] * natural_frequency**2
 
 
-def compute_damping(actuator_params: dict[str, float], natural_frequency: float = 10 * 2 * pi, damping_ratio: float = 2.0) -> float:
-    """Compute the damping of an actuator.
+def compute_damping(
+    actuator_params: dict[str, float],
+    natural_frequency: float = NATURAL_FREQUENCY,
+    damping_ratio: float = 2.0,
+) -> float:
+    """Return the joint damping in Nm s/rad.
 
     Args:
-        actuator_params: The parameters of the actuator.
-        natural_frequency: The natural frequency of the actuator in rad/s.
-        damping_ratio: The damping ratio of the actuator.
+        actuator_params: An actuator spec table. Reads ``armature`` in kg m^2.
+        natural_frequency: Closed-loop natural frequency in rad/s.
+        damping_ratio: Damping ratio. Above 1.0 is overdamped.
     """
     return 2.0 * damping_ratio * actuator_params["armature"] * natural_frequency
 
 
-def compute_action_scale(actuator_params: dict[str, float], natural_frequency: float = 10 * 2 * pi, action_scale_coefficient: float = 0.25) -> float:
-    """Compute the action scale from natural frequency and action scale coefficient.
+def compute_action_scale(
+    actuator_params: dict[str, float],
+    natural_frequency: float = NATURAL_FREQUENCY,
+    action_scale_coefficient: float = 0.25,
+) -> float:
+    """Return the policy action scale in rad.
+
+    This is the position offset whose stiffness torque reaches
+    ``action_scale_coefficient`` of the actuator's effort limit.
 
     Args:
-        actuator_params: The parameters of the actuator.
-        natural_frequency: The natural frequency of the actuator in rad/s.
-        action_scale_coefficient: The action scale coefficient.
+        actuator_params: An actuator spec table. Reads ``armature`` and ``effort_limit``.
+        natural_frequency: Closed-loop natural frequency in rad/s.
+        action_scale_coefficient: Fraction of the effort limit a unit action commands.
     """
     stiffness = compute_stiffness(actuator_params, natural_frequency)
     return action_scale_coefficient * actuator_params["effort_limit"] / stiffness
diff --git a/robot_assets/loader.py b/robot_assets/loader.py
index 39907cc..487ed21 100644
--- a/robot_assets/loader.py
+++ b/robot_assets/loader.py
@@ -9,13 +9,12 @@
 from urllib.request import Request, urlopen
 import zipfile
 
+# Robots live under robots/<robot>/, the franka_description layout the lite_description
+# ament package also uses.
+ROOT_DIR = "robots"
 
 _FETCH_LOCK = threading.Lock()
 
-# Robots live under robots/<robot>/ (the lite_description ament package keeps
-# its per-robot assets in a robots/ subdir, franka_description style).
-ROOT_DIR = "robots"
-
 
 def load(
     path: str | Path,
@@ -25,61 +24,52 @@ def load(
 ) -> Path:
     """Load a robot description file from GitHub, or return it from the local cache.
 
-    This function does the following under the hood:
-
-    1. If ``cache_dir / path`` already exists, return its resolved path.
-    2. Otherwise download the repository ZIP (GitHub API), extract the
-       ``robots/<robot>/`` subtree into ``cache_dir``, then return the resolved path.
+    Returns ``cache_dir / path`` when it exists. Otherwise downloads the repository ZIP,
+    extracts the ``robots/<robot>/`` subtree into ``cache_dir`` and returns the path.
 
     Args:
-        path (`str` | `pathlib.Path`):
-            Relative path inside the repo, e.g. ``"robots/lite/urdf/lite.urdf"``.
-            Must start with ``robots/<robot>/`` and must not be absolute.
-        repo_url (`str`, *optional*):
-            Standard ``https://github.com/owner/repo`` URL; only ``github.com`` is supported.
-        cache_dir (`str` | `pathlib.Path`, *optional*):
-            Root directory for cached ``robots/...``. Defaults to ``"data/"``.
-        timeout (`float`, *optional*):
-            HTTP timeout in seconds for the archive download.
+        path: Relative path inside the repo, such as ``"robots/lite/urdf/lite.urdf"``.
+            It must start with ``robots/<robot>/`` and must not be absolute.
+        repo_url: A standard ``https://github.com/owner/repo`` URL. Only github.com works.
+        cache_dir: Root directory for the cached ``robots/...`` tree.
+        timeout: HTTP timeout in seconds for the archive download.
 
     Returns:
-        `pathlib.Path`: Absolute path to the cached file.
+        Absolute path to the cached file.
     """
-
-    cache_dir = Path(cache_dir)
-    robot_name, relative_asset_path = parse_upstream_asset_path(path)
-    resolved_path = (cache_dir / relative_asset_path).resolve()
+    robot_name, relative_path = parse_upstream_asset_path(path)
+    resolved_path = (Path(cache_dir) / relative_path).resolve()
     if resolved_path.exists():
         return resolved_path
 
+    # One fetch at a time, and re-check inside the lock: a concurrent caller may have
+    # populated the cache while this one waited.
     with _FETCH_LOCK:
         if not resolved_path.exists():
-            fetch_robot_description(robot_name, repo_url, cache_dir, timeout)
+            fetch_robot_description(robot_name, repo_url, Path(cache_dir), timeout)
 
-    if resolved_path.exists():
-        return resolved_path
-
-    raise FileNotFoundError(
-        "Robot description asset is still missing after fetching "
-        f"'{robot_name}': {resolved_path}"
-    )
+    if not resolved_path.exists():
+        raise FileNotFoundError(
+            f"Robot description asset is still missing after fetching "
+            f"'{robot_name}': {resolved_path}"
+        )
+    return resolved_path
 
 
 def parse_upstream_asset_path(path: str | Path) -> tuple[str, Path]:
+    """Split an upstream asset path into its robot name and the path itself."""
     asset_path = Path(path).expanduser()
     if asset_path.is_absolute():
         raise ValueError(
             "Robot description asset paths must be relative upstream paths like "
             f"'robots/lite/urdf/lite.urdf', got {asset_path}"
         )
-
     parts = asset_path.parts
     if len(parts) < 3 or parts[0] != ROOT_DIR:
         raise ValueError(
             "Robot description asset paths must be of the form "
             f"'{ROOT_DIR}/<robot>/...', got {asset_path}"
         )
-
     return parts[1], asset_path
 
 
@@ -89,18 +79,18 @@ def fetch_robot_description(
     cache_dir: Path,
     timeout: float,
 ) -> None:
+    """Download the repository archive and copy one robot's subtree into the cache."""
     cache_dir.mkdir(parents=True, exist_ok=True)
-    target_dir = cache_dir / ROOT_DIR / robot_name
-
     with tempfile.TemporaryDirectory(prefix=f"robot_assets_{robot_name}_") as tmp:
         archive_path = Path(tmp) / "repo.zip"
         extracted_dir = Path(tmp) / robot_name
         download_archive(archive_path, repo_url, timeout)
         extract_robot_directory(archive_path, robot_name, extracted_dir, repo_url)
-        shutil.copytree(extracted_dir, target_dir, dirs_exist_ok=True)
+        shutil.copytree(extracted_dir, cache_dir / ROOT_DIR / robot_name, dirs_exist_ok=True)
 
 
 def download_archive(destination: Path, repo_url: str, timeout: float) -> None:
+    """Download the repository ZIP from the GitHub API to ``destination``."""
     request = Request(
         build_archive_url(repo_url),
         headers={
@@ -108,7 +98,6 @@ def download_archive(destination: Path, repo_url: str, timeout: float) -> None:
             "User-Agent": "robot-description-cache",
         },
     )
-
     try:
         with (
             urlopen(request, timeout=timeout) as response,
@@ -133,36 +122,36 @@ def extract_robot_directory(
     destination: Path,
     repo_url: str,
 ) -> None:
-    found_robot = False
+    """Extract one ``robots/<robot_name>/`` subtree from the archive into ``destination``.
 
+    GitHub's zipball wraps everything in a commit-named top directory, so the ``robots``
+    component is located by name rather than by a fixed depth.
+    """
+    found_robot = False
     with zipfile.ZipFile(archive_path) as archive:
         for info in archive.infolist():
             parts = Path(info.filename).parts
-            try:
-                robots_index = parts.index(ROOT_DIR)
-            except ValueError:
+            if ROOT_DIR not in parts:
                 continue
-
-            if len(parts) <= robots_index + 1 or parts[robots_index + 1] != robot_name:
+            index = parts.index(ROOT_DIR)
+            if len(parts) <= index + 1 or parts[index + 1] != robot_name:
                 continue
 
             found_robot = True
-            relative_path = Path(*parts[robots_index + 2 :])
-            output_path = destination / relative_path
-
+            output_path = destination / Path(*parts[index + 2:])
             if info.is_dir():
                 output_path.mkdir(parents=True, exist_ok=True)
                 continue
-
             output_path.parent.mkdir(parents=True, exist_ok=True)
-            with archive.open(info) as source_file, output_path.open("wb") as target_file:
-                shutil.copyfileobj(source_file, target_file)
+            with archive.open(info) as source, output_path.open("wb") as target:
+                shutil.copyfileobj(source, target)
 
     if not found_robot:
         raise FileNotFoundError(f"Robot '{robot_name}' was not found in {repo_url}.")
 
 
 def build_archive_url(repo_url: str) -> str:
+    """Derive the GitHub zipball API URL from a repository URL."""
     parsed_url = urlparse(repo_url.removesuffix(".git"))
     path_parts = [part for part in parsed_url.path.split("/") if part]
     if parsed_url.netloc != "github.com" or len(path_parts) != 2:
@@ -170,6 +159,5 @@ def build_archive_url(repo_url: str) -> str:
             "Only standard GitHub repository URLs are supported. "
             f"Could not derive archive URL from {repo_url!r}."
         )
-
     owner, repo = path_parts
     return f"https://api.github.com/repos/{owner}/{repo}/zipball"
diff --git a/robot_assets/workflow/finalize_urdf.py b/robot_assets/workflow/finalize_urdf.py
index ab28007..74dc557 100644
--- a/robot_assets/workflow/finalize_urdf.py
+++ b/robot_assets/workflow/finalize_urdf.py
@@ -1,11 +1,14 @@
-"""Finalize the flat URDF in place -- the kinematic hub the mjcf/xacro stages derive from.
+"""Finalize the flat URDF in place, the hub the mjcf and xacro stages derive from.
 
-Harmonizes each ``<limit effort>`` to ``joint_properties.json``, normalizes mesh paths to
-``../meshes/visual/``, and stamps the generated-asset banner. The hub stays
-``base_link``-free (``base_link`` is a ROS/KDL concern injected only into the description
-xacro), which keeps this stage idempotent and the MJCF rooted at the CAD root link.
+Welds the joints flagged fixed, harmonizes each ``<limit effort>`` to
+joint_properties.json, normalizes mesh paths to ``../meshes/visual/`` and stamps the
+generated-asset banner.
 
-Parallel to urdf_to_mjcf / urdf_to_xacro: exposes ``generate(robot_dir) -> list[Path]``.
+The hub stays ``base_link``-free, because ``base_link`` is a ROS and KDL concern that
+belongs only in the description xacro. That keeps this stage idempotent and the MJCF
+rooted at the CAD root link.
+
+Parallel to urdf_to_mjcf and urdf_to_xacro: exposes ``generate(robot_dir) -> list[Path]``.
 """
 
 import argparse
@@ -16,31 +19,28 @@
 from . import robot_model
 
 
-def ensure_autogen_comment(root: ET.Element, text: str) -> None:
-    """Idempotently make the first child of <robot> the generated-asset banner comment."""
-    while len(root) and not isinstance(root[0].tag, str):  # comment nodes have a non-str tag
-        root.remove(root[0])
-    root.insert(0, ET.Comment(text))
-
-
 def generate(robot_dir: Path) -> list[Path]:
-    robot_dir = Path(robot_dir)
+    """Rewrite ``urdf/<robot>.urdf`` in place and return the path."""
     robot = robot_dir.name
-    cad_dir = robot_dir / "cad"
     hub_urdf = robot_dir / "urdf" / f"{robot}.urdf"
     if not hub_urdf.exists():
         raise FileNotFoundError(
-            f"{hub_urdf} not found. Run the onshape stage first (full export), or commit "
-            f"the URDF so --from-cache has a hub to finalize.",
+            f"{hub_urdf} not found. Run the onshape stage first, or commit the URDF so "
+            f"this stage has a hub to finalize.",
         )
-    joint_properties = json.loads((cad_dir / "joint_properties.json").read_text())
+    joint_properties = json.loads((robot_dir / "cad" / "joint_properties.json").read_text())
 
     tree = robot_model.parse(hub_urdf)
     root = tree.getroot()
     robot_model.weld_joints(root, joint_properties)
     robot_model.harmonize_effort(root, joint_properties)
     robot_model.rewrite_mesh_filenames(root, lambda name: f"../meshes/visual/{name}")
-    ensure_autogen_comment(root, robot_model.autogen_comment(robot))
+
+    # Make the banner the first child again, dropping the one a previous run left.
+    # Comment nodes carry a non-str tag, which is how they are told from elements.
+    while len(root) and not isinstance(root[0].tag, str):
+        root.remove(root[0])
+    root.insert(0, ET.Comment(robot_model.autogen_comment(robot)))
 
     robot_model.serialize(tree, hub_urdf)
     return [hub_urdf]
diff --git a/robot_assets/workflow/generate.py b/robot_assets/workflow/generate.py
index 4edc642..8058a95 100644
--- a/robot_assets/workflow/generate.py
+++ b/robot_assets/workflow/generate.py
@@ -1,31 +1,35 @@
 """One converter, three formats: CAD -> URDF + MJCF + xacro.
 
-Orchestrates the generation DAG for a ``robots/<robot>/`` directory. The committed flat
-URDF (``urdf/<robot>.urdf`` + ``meshes/visual/``) is the kinematic hub; the MJCF and
-xacro are both derived from it, so the three formats share one kinematic origin (parity
-by construction).
-
-Stages (each runnable alone via ``--only``). The three format stages are sibling modules,
-each exposing ``generate(robot_dir) -> list[Path]``:
-  onshape  onshape_to_urdf : Onshape CAD -> urdf/<robot>.urdf + meshes/visual/  (--from-cache skips)
-  urdf     finalize_urdf   : finalize the hub (harmonise effort, ../meshes/visual/, base_link-free)
-  mjcf     urdf_to_mjcf    : MuJoCo compile + post-process + <option>
-  xacro    urdf_to_xacro   : description macro (+base_link) + ros2_control + assembly
+Runs the generation stages for a ``robots/<robot>/`` directory. The committed flat URDF
+(``urdf/<robot>.urdf`` plus ``meshes/visual/``) is the kinematic hub. The MJCF and the
+xacro both derive from it, so the three formats share one kinematic origin and cannot
+drift apart.
+
+Stages, each runnable alone with ``--only``. The three format stages are sibling modules
+that each expose ``generate(robot_dir) -> list[Path]``:
+
+  onshape  onshape_to_urdf : Onshape CAD -> urdf/<robot>.urdf + meshes/visual/
+  urdf     finalize_urdf   : finalize the hub (weld, harmonize effort, mesh paths)
+  mjcf     urdf_to_mjcf    : MuJoCo compile, post-process, <option>
+  xacro    urdf_to_xacro   : description macro (+base_link), ros2_control, assembly
   package                  : register the robot in the repo-root CMakeLists
 
+The onshape stage hits the Onshape API about 1000 times, so it is skipped whenever the
+URDF hub is already committed. Pass ``--force`` to re-export anyway.
+
 Usage:
-  robot-assets-generate lite_dummy                 # full pipeline (auto --from-cache if hub present)
+  robot-assets-generate lite_dummy
   robot-assets-generate lite_dummy --only mjcf,xacro
-  robot-assets-generate ./robots/lite_dummy --from-cache
+  robot-assets-generate ./robots/lite_dummy --force
 """
 
 import argparse
 from pathlib import Path
 import re
 
-from . import finalize_urdf, robot_model, urdf_to_mjcf, urdf_to_xacro
+from . import finalize_urdf, onshape_to_urdf, robot_model, urdf_to_mjcf, urdf_to_xacro
 
-STAGES = ["onshape", "urdf", "mjcf", "xacro", "package"]
+STAGES = ("onshape", "urdf", "mjcf", "xacro", "package")
 
 
 def _report(stage: str, written: list[Path]) -> None:
@@ -33,15 +37,8 @@ def _report(stage: str, written: list[Path]) -> None:
         print(f"[{stage}] wrote {path}")
 
 
-def stage_onshape(robot_dir: Path) -> None:
-    from . import onshape_to_urdf
-
-    print(f"[onshape] exporting {robot_dir.name} from Onshape (this hits the API)...")
-    onshape_to_urdf.export(robot_dir)
-
-
-def stage_package(robot_dir: Path, package: str) -> None:
-    """Idempotently register the robot in the repo-root CMakeLists ROBOTS list."""
+def register_in_cmake(robot_dir: Path) -> None:
+    """Add the robot to the repo-root CMakeLists ROBOTS list, if it is not there."""
     robot = robot_dir.name
     cmake = robot_dir.parent.parent / "CMakeLists.txt"  # robots/<robot>/ -> repo root
     if not cmake.exists():
@@ -55,33 +52,37 @@ def stage_package(robot_dir: Path, package: str) -> None:
     listed = match.group("body").split()
     if robot in listed:
         return
-    listed.append(robot)
-    new_block = "set(ROBOTS\n  " + "\n  ".join(sorted(listed)) + "\n)"
-    cmake.write_text(text[: match.start()] + new_block + text[match.end():])
+    block = "set(ROBOTS\n  " + "\n  ".join(sorted([*listed, robot])) + "\n)"
+    cmake.write_text(text[: match.start()] + block + text[match.end():])
     print(f"[package] registered {robot} in {cmake.name}")
 
 
 def generate(
     robot: str,
-    *,
     only: list[str] | None = None,
-    from_cache: bool = False,
+    force: bool = False,
     package: str = robot_model.DEFAULT_PACKAGE,
 ) -> None:
+    """Run the requested stages for one robot."""
+    unknown = sorted(set(only or ()) - set(STAGES))
+    if unknown:
+        raise ValueError(f"Unknown stage(s) {unknown}. Valid: {list(STAGES)}")
+
     robot_dir = robot_model.resolve_robot_dir(robot)
-    stages = only if only else list(STAGES)
+    stages = list(only) if only else list(STAGES)
 
     hub = robot_dir / "urdf" / f"{robot_dir.name}.urdf"
-    if "onshape" in stages and (from_cache or (only is None and hub.exists())):
-        if from_cache:
-            print("[onshape] skipped (--from-cache)")
-        else:
-            print(f"[onshape] skipped (committed URDF present at {hub}); pass --force to re-export")
-        stages = [s for s in stages if s != "onshape"]
+    # Skip the expensive export when the hub is committed, unless it was asked for by
+    # name (--only onshape) or forced. `only is None` implies stages == STAGES, which
+    # always contains "onshape".
+    if only is None and hub.exists() and not force:
+        print(f"[onshape] skipped (URDF hub present at {hub}); pass --force to re-export")
+        stages.remove("onshape")
 
     for stage in stages:
         if stage == "onshape":
-            stage_onshape(robot_dir)
+            print(f"[onshape] exporting {robot_dir.name} from Onshape (this hits the API)...")
+            onshape_to_urdf.export(robot_dir)
         elif stage == "urdf":
             _report("urdf", finalize_urdf.generate(robot_dir))
         elif stage == "mjcf":
@@ -89,25 +90,21 @@ def generate(
         elif stage == "xacro":
             _report("xacro", urdf_to_xacro.generate(robot_dir, package=package))
         elif stage == "package":
-            stage_package(robot_dir, package)
-        else:
-            raise ValueError(f"Unknown stage '{stage}'. Valid: {STAGES}")
+            register_in_cmake(robot_dir)
 
 
 def main(argv: list[str] | None = None) -> None:
     parser = argparse.ArgumentParser(description="Generate URDF + MJCF + xacro for a robot from CAD.")
     parser.add_argument("robot", help="Robot name (under ./robots/) or a path to a robot dir.")
-    parser.add_argument("--from-cache", action="store_true",
-                        help="Skip the Onshape export; reuse the committed urdf/ hub.")
     parser.add_argument("--force", action="store_true",
-                        help="Run the Onshape export even if a cached export exists.")
-    parser.add_argument("--only", help="Comma-separated subset of stages to run, e.g. 'mjcf,xacro'.")
-    parser.add_argument("--package", default=robot_model.DEFAULT_PACKAGE, help="Owning ament package name.")
+                        help="Re-run the Onshape export even if the URDF hub is committed.")
+    parser.add_argument("--only", help="Comma-separated subset of stages, e.g. 'mjcf,xacro'.")
+    parser.add_argument("--package", default=robot_model.DEFAULT_PACKAGE,
+                        help="Owning ament package name.")
     args = parser.parse_args(argv)
 
     only = [s.strip() for s in args.only.split(",")] if args.only else None
-    from_cache = args.from_cache and not args.force
-    generate(args.robot, only=only, from_cache=from_cache, package=args.package)
+    generate(args.robot, only=only, force=args.force, package=args.package)
 
 
 if __name__ == "__main__":
diff --git a/robot_assets/workflow/onshape_to_urdf.py b/robot_assets/workflow/onshape_to_urdf.py
index f7b8c84..0213234 100644
--- a/robot_assets/workflow/onshape_to_urdf.py
+++ b/robot_assets/workflow/onshape_to_urdf.py
@@ -1,18 +1,18 @@
-"""Stage 1 of the converter: export the raw URDF + meshes from Onshape CAD.
+"""Stage 1 of the converter: export the raw URDF and meshes from Onshape CAD.
 
-Wraps the external `onshape-to-robot` tool and normalises its output into the
+Wraps the external ``onshape-to-robot`` tool and normalizes its output into the
 robots/<robot>/ layout:
 
     robots/<robot>/
       cad/config.json          (input: Onshape doc + export options)
       cad/scad/                (input: custom collider sources)
-      urdf/<robot>.urdf        (output: flat URDF -- the committed kinematic hub)
+      urdf/<robot>.urdf        (output: the flat URDF, the committed kinematic hub)
       meshes/visual/*.stl      (output: merged visual meshes, one copy)
 
-The flat URDF is the committed, cacheable hub; the `urdf` finalize stage then
-harmonizes its effort limits, and the mjcf/xacro stages derive from it. With a
-committed hub, iterating on physics.json / ros2_control.json via `--from-cache`
-never re-hits the Onshape API (~1000 requests per export).
+The flat URDF is the committed, cacheable hub. The ``urdf`` finalize stage then welds and
+harmonizes it, and the mjcf and xacro stages derive from it. With a committed hub, work on
+physics.json or ros2_control.json never re-hits the Onshape API, which costs about 1000
+requests per export.
 """
 
 import argparse
@@ -25,24 +25,17 @@
 from . import robot_model
 
 
-def _onshape_to_robot_bin() -> str:
-    """Locate the onshape-to-robot CLI (PATH, else alongside the running interpreter).
-
-    Raises:
-        FileNotFoundError: If the CLI is missing, i.e. the `cad` extra is not installed.
-    """
-    binary = shutil.which("onshape-to-robot") or str(Path(sys.executable).parent / "onshape-to-robot")
-    if not Path(binary).exists():
-        raise FileNotFoundError(
-            "The onshape-to-robot CLI was not found. It ships with the CAD toolchain rather than "
-            "the base install; install it with `pip install robot-assets[cad]`."
-        )
-    return binary
+def export(robot_dir: Path, keep_assets: bool = False, convert: bool = False) -> Path:
+    """Run onshape-to-robot for ``robot_dir`` and place the outputs in the cad/ layout.
 
+    Args:
+        robot_dir: The ``robots/<robot>/`` directory to export.
+        keep_assets: Keep ``cad/assets/`` and ``cad/robot.pkl`` after the run.
+        convert: Rebuild from the local ``robot.pkl`` instead of calling the Onshape API.
 
-def export(robot_dir: Path, *, keep_assets: bool = False, convert: bool = False) -> Path:
-    """Run onshape-to-robot for ``robot_dir`` and place outputs in the cad/ layout."""
-    robot_dir = Path(robot_dir)
+    Returns:
+        Path to the written ``urdf/<robot>.urdf`` hub.
+    """
     robot = robot_dir.name
     cad_dir = robot_dir / "cad"
     config_path = cad_dir / "config.json"
@@ -59,12 +52,18 @@ def export(robot_dir: Path, *, keep_assets: bool = False, convert: bool = False)
         for scad_file in scad_dir.iterdir():
             shutil.copy(scad_file, assets_dir / scad_file.name)
 
-    arguments = [_onshape_to_robot_bin(), str(cad_dir)]
+    binary = shutil.which("onshape-to-robot") or str(Path(sys.executable).parent / "onshape-to-robot")
+    if not Path(binary).exists():
+        raise FileNotFoundError(
+            "The onshape-to-robot CLI was not found. It ships with the CAD toolchain rather than "
+            "the base install; install it with `pip install robot-assets[cad]`."
+        )
+    arguments = [binary, str(cad_dir)]
     if convert:
-        # Offline: reload the existing robot.pkl instead of hitting the Onshape API.
-        # --save-pickle must NOT be combined with --convert: onshape-to-robot runs its
-        # save branch before the convert branch, but no robot is built on the convert
-        # path, so the two together raise a NameError.
+        # Offline: reload the existing robot.pkl. --save-pickle must NOT be combined with
+        # --convert, because onshape-to-robot runs its save branch before its convert
+        # branch and no robot is built on the convert path, so the two together raise a
+        # NameError.
         arguments.append("--convert")
     elif keep_assets:
         # Build path: persist robot.pkl so later runs can re-derive offline via --convert.
@@ -73,23 +72,21 @@ def export(robot_dir: Path, *, keep_assets: bool = False, convert: bool = False)
 
     # Merged visual meshes -> the single meshes/visual/ copy.
     merged = assets_dir / "merged"
-    visual_dir = robot_dir / "meshes" / "visual"
     if merged.exists():
+        visual_dir = robot_dir / "meshes" / "visual"
         visual_dir.mkdir(parents=True, exist_ok=True)
         shutil.copytree(merged, visual_dir, dirs_exist_ok=True)
 
-    # Flat URDF -> urdf/<robot>.urdf, with mesh refs pointed at meshes/visual/
-    # and the ROS package:// scheme stripped. The `urdf` finalize stage then
-    # harmonizes effort limits in place.
+    # Flat URDF -> urdf/<robot>.urdf, with mesh refs pointed at meshes/visual/ and the ROS
+    # package:// scheme stripped. The finalize stage then harmonizes it in place.
+    hub_urdf = robot_dir / "urdf" / f"{robot}.urdf"
+    hub_urdf.parent.mkdir(parents=True, exist_ok=True)
     produced_urdf = cad_dir / f"{output_filename}.urdf"
-    urdf_dir = robot_dir / "urdf"
-    urdf_dir.mkdir(parents=True, exist_ok=True)
-    hub_urdf = urdf_dir / f"{robot}.urdf"
-
-    content = produced_urdf.read_text()
-    content = content.replace("assets/merged/", "../meshes/visual/")
-    content = content.replace("package://", "")
-    hub_urdf.write_text(content)
+    hub_urdf.write_text(
+        produced_urdf.read_text()
+        .replace("assets/merged/", "../meshes/visual/")
+        .replace("package://", "")
+    )
     produced_urdf.unlink(missing_ok=True)
 
     if not keep_assets:
diff --git a/robot_assets/workflow/robot_model.py b/robot_assets/workflow/robot_model.py
index ac79e13..53d5c59 100644
--- a/robot_assets/workflow/robot_model.py
+++ b/robot_assets/workflow/robot_model.py
@@ -1,16 +1,17 @@
-"""Full-fidelity URDF parsing + structural transforms shared by the generator stages.
+"""URDF parsing and the structural transforms the generator stages share.
 
-The committed flat URDF (``urdf/<robot>.urdf``) is the single kinematic source/hub.
-This module parses it once and exposes the transforms every emitter needs:
+The committed flat URDF (``urdf/<robot>.urdf``) is the single kinematic source. This
+module parses it and exposes the transforms every emitter needs:
 
-* :func:`harmonize_effort`  -- tighten ``<limit effort>`` to the Robstride spec in
-  ``joint_properties.json`` (the raw export leaves it at the Onshape default of 100).
-* :func:`rewrite_mesh_filenames` -- retarget mesh references per consumer
-  (``package://`` for ROS, ``../meshes/visual/`` for the flat URDF, etc.).
-* :func:`inject_base_link` -- add the massless ``base_link`` root that KDL /
-  robot_state_publisher want (the CAD root link carries inertia).
+* :func:`weld_joints`      -- retire a CAD-real DoF flagged ``"fixed"`` in joint_properties.
+* :func:`harmonize_effort` -- tighten ``<limit effort>`` to the value in joint_properties,
+  because the raw Onshape export leaves it at the default of 100.
+* :func:`rewrite_mesh_filenames` -- retarget mesh references per consumer, ``package://``
+  for ROS and ``../meshes/visual/`` for the flat URDF.
+* :func:`inject_base_link` -- add the massless ``base_link`` root that KDL and
+  robot_state_publisher want, since the CAD root link carries inertia.
 
-Comments and child order are preserved so generated files stay readable/reviewable.
+Comments and child order survive the round trip, so generated files stay reviewable.
 """
 
 from collections.abc import Callable
@@ -20,95 +21,86 @@
 
 XACRO_NS = "http://www.ros.org/wiki/xacro"
 
+# Per-robot assets live under ./<ROBOTS_DIR>/<robot>/, the franka_description layout.
+ROBOTS_DIR = "robots"
+# Owning ament package name, used in package:// URLs and $(find ...).
+DEFAULT_PACKAGE = "lite_description"
+
+# Joint types that carry a movable axis, limits and dynamics.
+MOVABLE_JOINT_TYPES = frozenset({"revolute", "prismatic"})
+
 
 def parse(urdf_path: str | Path) -> ET.ElementTree:
-    """Parse a URDF, preserving comments (so re-emitted files keep their structure)."""
+    """Parse a URDF, keeping comments so re-emitted files keep their structure."""
     parser = ET.XMLParser(target=ET.TreeBuilder(insert_comments=True))
     return ET.parse(urdf_path, parser=parser)
 
 
-def link_names(root: ET.Element) -> list[str]:
-    return [link.get("name") for link in root.findall("link") if link.get("name")]
-
-
-def child_link_names(root: ET.Element) -> set[str]:
-    children: set[str] = set()
-    for joint in root.findall("joint"):
-        child = joint.find("child")
-        if child is not None and child.get("link"):
-            children.add(child.get("link"))
-    return children
-
-
 def root_link(root: ET.Element) -> str:
-    """The single link that is never a joint's child (the kinematic root)."""
-    children = child_link_names(root)
-    roots = [name for name in link_names(root) if name not in children]
+    """Return the one link that is never a joint's child, the kinematic root."""
+    children = {
+        joint.find("child").get("link") for joint in root.findall("joint")
+        if joint.find("child") is not None
+    }
+    roots = [link.get("name") for link in root.findall("link")
+             if link.get("name") not in children]
     if len(roots) != 1:
         raise ValueError(f"Expected exactly one root link, found {roots}.")
     return roots[0]
 
 
 def joint_limits(root: ET.Element) -> dict[str, dict[str, float]]:
-    """Map joint name -> {lower, upper, effort, velocity} from ``<limit>`` (radians)."""
-    limits: dict[str, dict[str, float]] = {}
+    """Map joint name -> {lower, upper} from each ``<limit>``, in radians.
+
+    A joint whose ``<limit>`` omits either bound is skipped. URDF makes both optional,
+    and a continuous joint legitimately has neither.
+    """
+    limits = {}
     for joint in root.findall("joint"):
-        name = joint.get("name")
         limit = joint.find("limit")
-        if name is None or limit is None:
+        if limit is None:
             continue
-        limits[name] = {
-            key: float(limit.get(key))
-            for key in ("lower", "upper", "effort", "velocity")
-            if limit.get(key) is not None
-        }
+        lower, upper = limit.get("lower"), limit.get("upper")
+        if lower is not None and upper is not None:
+            limits[joint.get("name")] = {"lower": float(lower), "upper": float(upper)}
     return limits
 
 
 def resolve_properties(name: str, properties: dict) -> dict | None:
-    """Look up per-joint config by exact name, then by regex key (``_``-keys ignored)."""
+    """Look up per-joint config by exact name, then by regex key. ``_`` keys are notes."""
     if name in properties:
         return properties[name]
     for pattern, config in properties.items():
-        if pattern.startswith("_"):
-            continue
-        try:
-            if re.fullmatch(pattern, name):
-                return config
-        except re.error:
-            continue
+        if not pattern.startswith("_") and re.fullmatch(pattern, name):
+            return config
     return None
 
 
 def harmonize_effort(root: ET.Element, joint_properties: dict) -> None:
-    """Set each revolute ``<limit effort>`` to ``effort_limit`` from joint_properties."""
+    """Set each movable joint's ``<limit effort>`` to its ``effort_limit``."""
     for joint in root.findall("joint"):
-        name = joint.get("name")
-        if joint.get("type") not in {"revolute", "prismatic"} or name is None:
-            continue
-        config = resolve_properties(name, joint_properties)
-        if config is None or "effort_limit" not in config:
+        if joint.get("type") not in MOVABLE_JOINT_TYPES:
             continue
+        config = resolve_properties(joint.get("name"), joint_properties) or {}
         limit = joint.find("limit")
-        if limit is not None:
+        if "effort_limit" in config and limit is not None:
             limit.set("effort", str(config["effort_limit"]))
 
 
 def weld_joints(root: ET.Element, joint_properties: dict) -> None:
-    """Convert joints flagged ``"fixed": true`` in joint_properties to fixed joints.
+    """Convert joints flagged ``"fixed": true`` in joint_properties into fixed joints.
 
-    Drops the movable-only children (``<axis>`` / ``<limit>`` / ``<dynamics>`` /
-    ``<mimic>``) so the joint rigidly welds its child to its parent. This retires a
-    CAD-real DoF (e.g. a locked waist) from the kinematic hub -- so the description
-    xacro, the MJCF (MuJoCo welds a fixed joint), and URDF<->MJCF parity all see a
-    rigid weld -- without re-exporting from Onshape.
+    Drops the movable-only children, so the joint rigidly welds its child to its parent.
+    This retires a CAD-real DoF, a locked waist for example, from the kinematic hub
+    without a re-export from Onshape. The description xacro, the MJCF, where MuJoCo welds
+    a fixed joint, and the URDF-to-MJCF parity check then all see one rigid weld.
     """
     for joint in root.findall("joint"):
-        name = joint.get("name")
-        if name is None or joint.get("type") == "fixed":
+        # Any non-fixed type can be welded, `continuous` included.
+        if joint.get("type") == "fixed":
             continue
-        config = resolve_properties(name, joint_properties)
-        if not (config and config.get("fixed")):
+        config = resolve_properties(joint.get("name"), joint_properties) or {}
+        if not config.get("fixed"):
             continue
         joint.set("type", "fixed")
         for tag in ("axis", "limit", "dynamics", "mimic"):
@@ -117,7 +109,7 @@ def weld_joints(root: ET.Element, joint_properties: dict) -> None:
 
 
 def rewrite_mesh_filenames(root: ET.Element, rewrite: Callable[[str], str]) -> None:
-    """Rewrite every ``<mesh filename>``; ``rewrite`` receives the file basename."""
+    """Rewrite every ``<mesh filename>``. ``rewrite`` receives the file basename."""
     for mesh in root.iter("mesh"):
         filename = mesh.get("filename")
         if filename:
@@ -125,14 +117,13 @@ def rewrite_mesh_filenames(root: ET.Element, rewrite: Callable[[str], str]) -> N
 
 
 def inject_base_link(root: ET.Element, base_name: str, child_name: str) -> None:
-    """Prepend a massless ``base_name`` link + fixed joint to ``child_name`` (the CAD root)."""
-    base_link = ET.Element("link", {"name": base_name})
+    """Prepend a massless ``base_name`` link and a fixed joint to the CAD root link."""
     joint = ET.Element("joint", {"name": f"{base_name}_to_{child_name}", "type": "fixed"})
     ET.SubElement(joint, "parent", {"link": base_name})
     ET.SubElement(joint, "child", {"link": child_name})
     ET.SubElement(joint, "origin", {"xyz": "0 0 0", "rpy": "0 0 0"})
     root.insert(0, joint)
-    root.insert(0, base_link)
+    root.insert(0, ET.Element("link", {"name": base_name}))
 
 
 def serialize(tree: ET.ElementTree, path: str | Path) -> None:
@@ -142,14 +133,15 @@ def serialize(tree: ET.ElementTree, path: str | Path) -> None:
 
 
 def to_string(element: ET.Element) -> str:
+    """Indent an element and return it as XML text."""
     ET.indent(element, space="  ")
     return ET.tostring(element, encoding="unicode")
 
 
 def autogen_comment(robot: str) -> str:
-    """Banner text (no ``<!-- -->`` markers) marking a generated asset file.
+    """Return the banner text that marks a generated asset, without ``<!-- -->``.
 
-    Used verbatim as an XML comment at the top of every generated URDF / MJCF / xacro
+    Used verbatim as an XML comment at the top of every generated URDF, MJCF and xacro,
     so the source and the regenerate command are obvious to anyone who opens the file.
     """
     # NB: an XML comment may not contain '--', so keep the text dash-free.
@@ -159,16 +151,6 @@ def autogen_comment(robot: str) -> str:
     )
 
 
-# ---------------------------------------------------------------------------
-# Repository layout (shared by the converter stages and their CLIs)
-# ---------------------------------------------------------------------------
-
-# Per-robot assets live under ./<ROBOTS_DIR>/<robot>/ (franka_description layout).
-ROBOTS_DIR = "robots"
-# Owning ament package name, used in package:// URLs and $(find ...).
-DEFAULT_PACKAGE = "lite_description"
-
-
 def resolve_robot_dir(robot: str) -> Path:
     """Accept a path to a robot dir, or a robot name under ./<ROBOTS_DIR>/<name>."""
     path = Path(robot)
diff --git a/robot_assets/workflow/urdf_to_mjcf.py b/robot_assets/workflow/urdf_to_mjcf.py
index 59a0b2a..5a16d8c 100644
--- a/robot_assets/workflow/urdf_to_mjcf.py
+++ b/robot_assets/workflow/urdf_to_mjcf.py
@@ -1,17 +1,18 @@
-"""Compile a raw URDF into a post-processed MJCF (training + deployment sim asset).
-
-Pipeline (called by ``generate.py``; the flat URDF is the hub):
-  raw URDF + meshes  ->  MuJoCo compile  ->  post-process:
-    * replace cylinder geoms with capsules
-    * inject <option> physics tuning (from cad/physics.json)
-    * synthesize <position> actuators (forcerange from joint_properties effort_limit;
-      no <sensor> block -- see add_actuators)
-    * set per-joint frictionloss / armature (from joint_properties)
-  ->  mjcf/<robot>.xml  (meshdir -> ../meshes/visual/)
-
-Mesh resolution is decoupled from the URDF's relative paths: mesh refs are rewritten
-to bare basenames and MuJoCo is pointed at the real meshes dir during compilation, so
-this works regardless of where the raw URDF lives.
+"""Compile the URDF hub into a post-processed MJCF, the training and deployment sim asset.
+
+Called by ``generate.py``. The flat URDF is the hub:
+
+    URDF + meshes  ->  MuJoCo compile  ->  post-process  ->  mjcf/<robot>.xml
+
+Post-processing replaces cylinder geoms with capsules, injects the ``<option>`` physics
+tuning from ``cad/physics.json``, synthesizes one ``<position>`` actuator per actuated
+joint, and sets per-joint frictionloss and armature from ``cad/joint_properties.json``.
+Floating-base, IMU and contact handling are per-variant opt-ins, also from physics.json.
+
+The compiled model is parsed once and written once, so the intermediate states never
+reach disk. Mesh resolution is decoupled from the URDF's own relative paths: mesh refs
+become bare basenames and MuJoCo is pointed at the real meshes dir while it compiles, so
+this works wherever the URDF lives.
 """
 
 import argparse
@@ -30,82 +31,94 @@
 
 from . import robot_model
 
-# Compiler options applied to the URDF before MuJoCo import (meshdir is set separately
-# to the real meshes dir so compilation resolves the STLs).
-MUJOCO_COMPILER_OPTIONS = {
+# Applied to the URDF before MuJoCo imports it. meshdir is set separately, to the real
+# meshes dir, so compilation resolves the STLs.
+COMPILER_OPTIONS = {
     "discardvisual": "false",
     "fusestatic": "false",
     "angle": "radian",
 }
 
+# Indent width MuJoCo's own XML writer uses, so synthesized sections match the rest.
+INDENT = "  "
 
-def add_mujoco_compiler_tag(urdf_file_path: Path, meshdir: str) -> None:
-    tree = ET.parse(urdf_file_path)
-    root = tree.getroot()
-
-    mujoco_tag = root.find("mujoco")
-    if mujoco_tag is None:
-        mujoco_tag = ET.SubElement(root, "mujoco")
+# Where the generated MJCF looks for its meshes, relative to mjcf/<robot>.xml.
+MESHDIR = "../meshes/visual/"
 
-    compiler_tag = mujoco_tag.find("compiler")
-    if compiler_tag is None:
-        compiler_tag = ET.SubElement(mujoco_tag, "compiler")
 
-    compiler_tag.set("meshdir", meshdir)
-    for key, value in MUJOCO_COMPILER_OPTIONS.items():
-        compiler_tag.set(key, value)
-
-    tree.write(urdf_file_path, encoding="utf-8", xml_declaration=True)
+def _joint_property(joint_name: str, joint_properties: dict, key: str):
+    """Return one property of a joint, by exact name then by regex key."""
+    config = robot_model.resolve_properties(joint_name, joint_properties)
+    if config is None:
+        raise ValueError(
+            f"No joint properties found for joint '{joint_name}'. "
+            "Add an exact or regex entry to joint_properties.json.",
+        )
+    if key not in config:
+        raise ValueError(
+            f"Joint '{joint_name}' is missing required attribute '{key}' "
+            "in joint_properties.json.",
+        )
+    return config[key]
 
 
-def save_mjcf_from_urdf(urdf_path: Path, out_xml_path: Path) -> None:
-    model = mujoco.MjModel.from_xml_path(str(urdf_path))
-    mujoco.mj_saveLastXML(str(out_xml_path), model)
+def _section(root: ET.Element, tag: str, before: str | None = None) -> ET.Element:
+    """Return an empty top-level section, creating or clearing it as needed."""
+    section = root.find(tag)
+    if section is not None:
+        section.clear()
+        return section
 
+    section = ET.Element(tag)
+    sibling = root.find(before) if before else None
+    if sibling is None:
+        root.append(section)
+    else:
+        root.insert(list(root).index(sibling), section)
+    return section
 
-def set_compiler_meshdir(xml_file_path: Path, meshdir: str) -> None:
-    tree = ET.parse(xml_file_path)
-    root = tree.getroot()
-    compiler = root.find("compiler")
-    if compiler is None:
-        compiler = ET.Element("compiler")
-        root.insert(0, compiler)
-    compiler.set("meshdir", meshdir)
-    tree.write(xml_file_path, encoding="utf-8", xml_declaration=True)
 
+def _indent_section(root: ET.Element, section: ET.Element) -> None:
+    """Lay a synthesized top-level section out one element per line.
 
-def prepend_comment(xml_file_path: Path, text: str) -> None:
-    """Insert ``text`` as an XML comment immediately inside the MJCF root element."""
-    tree = ET.parse(xml_file_path)
-    root = tree.getroot()
-    comment = ET.Comment(text)
-    comment.tail = "\n  "
-    root.insert(0, comment)
-    tree.write(xml_file_path, encoding="utf-8", xml_declaration=True)
+    ElementTree gives appended elements no whitespace, so a section built here would
+    serialize as one unreadable line while the surrounding model stays indented. This
+    touches the line breaks between top-level sections and the children of ``section``.
+    Bodies written by MuJoCo keep their existing layout.
+    """
+    ET.indent(section, space=INDENT, level=1)
+    for child in root:
+        child.tail = "\n" + INDENT
+    root[-1].tail = "\n"  # The last section closes the file, so dedent for </mujoco>.
 
 
 # ---------------------------------------------------------------------------
-# joint_properties lookup
+# MuJoCo compile
 # ---------------------------------------------------------------------------
 
 
-def resolve_joint_properties(joint_name: str, joint_properties: dict) -> dict:
-    config = robot_model.resolve_properties(joint_name, joint_properties)
-    if config is None:
-        raise ValueError(
-            f"No joint properties found for joint '{joint_name}'. "
-            "Add an exact or regex entry to joint_properties.json.",
-        )
-    return config
+def compile_mjcf(urdf_path: Path, meshes_dir: Path, work_dir: Path) -> ET.Element:
+    """Compile a URDF with MuJoCo and return the saved model's root element."""
+    tree = robot_model.parse(urdf_path)
+    robot_model.rewrite_mesh_filenames(tree.getroot(), lambda name: name)
+
+    # NB: an Element with no children is falsy, so these must test against None.
+    mujoco_tag = tree.getroot().find("mujoco")
+    if mujoco_tag is None:
+        mujoco_tag = ET.SubElement(tree.getroot(), "mujoco")
+    compiler = mujoco_tag.find("compiler")
+    if compiler is None:
+        compiler = ET.SubElement(mujoco_tag, "compiler")
+    compiler.set("meshdir", str(meshes_dir.resolve()))
+    for key, value in COMPILER_OPTIONS.items():
+        compiler.set(key, value)
 
+    urdf_copy = work_dir / urdf_path.name
+    tree.write(urdf_copy, encoding="utf-8", xml_declaration=True)
 
-def require_joint_attribute(joint_name: str, joint_config: dict, attribute_name: str):
-    if attribute_name not in joint_config:
-        raise ValueError(
-            f"Joint '{joint_name}' is missing required attribute '{attribute_name}' "
-            "in joint_properties.json.",
-        )
-    return joint_config[attribute_name]
+    saved = work_dir / "mjmodel.xml"
+    mujoco.mj_saveLastXML(str(saved), mujoco.MjModel.from_xml_path(str(urdf_copy)))
+    return ET.parse(saved).getroot()
 
 
 # ---------------------------------------------------------------------------
@@ -113,389 +126,255 @@ def require_joint_attribute(joint_name: str, joint_config: dict, attribute_name:
 # ---------------------------------------------------------------------------
 
 
-def ensure_section(root: ET.Element, tag_name: str, before_tag_name: str | None = None) -> ET.Element:
-    section = root.find(tag_name)
-    if section is not None:
-        section.clear()
-        return section
-
-    section = ET.Element(tag_name)
-    if before_tag_name is None:
-        root.append(section)
-        return section
+def replace_cylinders_with_capsules(root: ET.Element) -> int:
+    """Retype every cylinder geom as a capsule. Returns how many changed."""
+    cylinders = [geom for geom in root.iter("geom") if geom.get("type") == "cylinder"]
+    for geom in cylinders:
+        geom.set("type", "capsule")
+    return len(cylinders)
 
-    before_section = root.find(before_tag_name)
-    if before_section is not None:
-        root.insert(list(root).index(before_section), section)
-    else:
-        root.append(section)
-    return section
 
+def add_option(root: ET.Element, options: dict) -> None:
+    """Set the MuJoCo ``<option>`` attributes from physics.json.
 
-def add_option_tag(xml_file_path: Path, physics_options: dict) -> None:
-    if not physics_options:
+    A variant without physics.json gets no ``<option>`` element at all, rather than an
+    empty one, so its MJCF keeps MuJoCo's own defaults visible.
+    """
+    if not options:
         return
-    tree = ET.parse(xml_file_path)
-    root = tree.getroot()
-
     option = root.find("option")
     if option is None:
         option = ET.Element("option")
         compiler = root.find("compiler")
-        index = list(root).index(compiler) + 1 if compiler is not None else 0
-        root.insert(index, option)
-
-    for key, value in physics_options.items():
-        if key.startswith("_"):
-            continue
-        option.set(key, str(value))
-
-    tree.write(xml_file_path, encoding="utf-8", xml_declaration=True)
-
-
-def format_motor_forcerange_from_effort_limit(effort_limit) -> str:
-    """MuJoCo motor `forcerange` as symmetric +/-|effort_limit| (Nm for revolute joints)."""
-    if isinstance(effort_limit, (int, float)):
-        mag = abs(effort_limit)
-        return f"-{mag} {mag}"
-    raise ValueError(
-        f"effort_limit must be a number, got {type(effort_limit).__name__}: {effort_limit!r}",
-    )
-
-
-def add_actuators(xml_file_path: Path, joint_properties: dict) -> None:
-    """Synthesize one <position> actuator per actuated joint. Emits no <sensor> block.
-
-    <position> rather than <motor> because the joint-level PD belongs INSIDE the
-    physics step: MuJoCo evaluates actuators every ``mj_step``, which mirrors the
-    real RobStride drive closing its onboard loop at ~1 kHz independently of the
-    host rate, and lets ``implicitfast`` integrate the damping term implicitly (the
-    reason a stiff PD stays stable at a coarse timestep, and how mjlab trains).
-    A <motor> instead makes ``ctrl`` a raw torque, which forces the host to sample
-    the PD once per controller_manager tick.
-
-    ``kp``/``kv`` are deliberately left at MuJoCo's defaults: the operative gains
-    are mode-dependent (standby, policy, damping all differ) and arrive over
-    ros2_control's stiffness/damping command interfaces, so MujocoSystem overwrites
-    ``actuator_gainprm``/``actuator_biasprm`` every tick. Values baked here would
-    only mislead.
-
-    NO ``ctrlrange``/``ctrllimited`` is emitted, and that is load-bearing: an RL
-    policy is allowed to command a position setpoint BEYOND the mechanical joint
-    limit in order to hold a saturating torque, so clamping the setpoint would
-    silently cap the achievable torque. ``forcerange`` still bounds the output,
-    which is the limit that is physically real.
-
-    jointpos/jointvel sensors are intentionally omitted. They are redundant with
-    mjData.qpos/qvel -- mjlab reads joint state from the Entity/Articulation data,
-    not from named MJCF sensors -- and they make the model unloadable under
+        root.insert(list(root).index(compiler) + 1 if compiler is not None else 0, option)
+    for key, value in options.items():
+        if not key.startswith("_"):
+            option.set(key, str(value))
+
+
+def add_actuators(root: ET.Element, joint_properties: dict) -> None:
+    """Synthesize one ``<position>`` actuator per actuated joint. Emits no ``<sensor>``.
+
+    ``<position>`` rather than ``<motor>`` because the joint-level PD belongs inside the
+    physics step. MuJoCo evaluates actuators every ``mj_step``, which mirrors the real
+    RobStride drive closing its onboard loop at about 1 kHz independently of the host
+    rate, and lets ``implicitfast`` integrate the damping term implicitly. That is why a
+    stiff PD stays stable at a coarse timestep, and it is how mjlab trains. A ``<motor>``
+    makes ``ctrl`` a raw torque, which forces the host to sample the PD once per
+    controller_manager tick.
+
+    ``kp`` and ``kv`` stay at MuJoCo's defaults on purpose. The operative gains are
+    mode-dependent, because standby, policy and damping all differ, and they arrive over
+    the ros2_control stiffness and damping command interfaces. MujocoSystem therefore
+    overwrites ``actuator_gainprm`` and ``actuator_biasprm`` every tick, so values baked
+    in here would only mislead.
+
+    No ``ctrlrange`` or ``ctrllimited`` is emitted, and that is load-bearing. An RL policy
+    may command a position setpoint beyond the mechanical joint limit to hold a saturating
+    torque, so clamping the setpoint would silently cap the achievable torque.
+    ``forcerange`` still bounds the output, which is the limit that is physically real.
+
+    jointpos and jointvel sensors are omitted for two reasons. They duplicate
+    mjData.qpos/qvel, because mjlab reads joint state from the Entity/Articulation data
+    and not from named MJCF sensors. They also make the model unloadable under
     mujoco_ros2_control: its plugin init loops over every sensor and builds
     ``std::string(mj_id2name(model, mjOBJ_SITE, sensor_objid))``
-    (mujoco_ros2_control.cpp:124), which is null for a joint sensor when the model
-    has no <site>s -> SIGABRT. Keeping only actuators leaves the single MJCF usable
-    by both the RL/training sim and ros2_control.
+    (mujoco_ros2_control.cpp:124), which is null for a joint sensor when the model has no
+    ``<site>`` elements, and the process aborts. Keeping only actuators leaves the single
+    MJCF usable by both the RL sim and ros2_control.
     """
-    tree = ET.parse(xml_file_path)
-    root = tree.getroot()
-
-    joints: list[str] = []
-    for joint in root.iter("joint"):
-        joint_name = joint.get("name")
-        if joint_name and joint.get("actuatorfrcrange"):
-            joints.append(joint_name)
-
+    joints = [
+        joint.get("name") for joint in root.iter("joint")
+        if joint.get("name") and joint.get("actuatorfrcrange")
+    ]
     if not joints:
         print("No joints with actuatorfrcrange found in XML")
         return
 
-    actuator_section = ensure_section(root, "actuator")
-
+    section = _section(root, "actuator")
     for joint_name in joints:
-        actuator = ET.SubElement(actuator_section, "position")
+        effort_limit = abs(_joint_property(joint_name, joint_properties, "effort_limit"))
+        actuator = ET.SubElement(section, "position")
         actuator.set("name", joint_name)
         actuator.set("joint", joint_name)
-        joint_config = resolve_joint_properties(joint_name, joint_properties)
-        effort_limit = require_joint_attribute(joint_name, joint_config, "effort_limit")
-        actuator.set("forcerange", format_motor_forcerange_from_effort_limit(effort_limit))
-
-    tree.write(xml_file_path, encoding="utf-8", xml_declaration=True)
+        actuator.set("forcerange", f"-{effort_limit} {effort_limit}")
+    _indent_section(root, section)
 
 
-def add_freejoint(xml_file_path: Path) -> None:
-    tree = ET.parse(xml_file_path)
-    root = tree.getroot()
-
-    worldbody = root.find("worldbody")
-    first_body = worldbody.find("body") if worldbody is not None else None
-    if first_body is None:
-        print("No body element found in worldbody")
-        return
-
+def add_freejoint(root: ET.Element) -> None:
+    """Give the root body a 6-DoF free joint, making the base float."""
     freejoint = ET.Element("joint")
     freejoint.set("name", "floating_base_joint")
     freejoint.set("type", "free")
     freejoint.set("limited", "false")
     freejoint.set("actuatorfrclimited", "false")
-    first_body.insert(0, freejoint)
-
-    tree.write(xml_file_path, encoding="utf-8", xml_declaration=True)
+    root.find("worldbody").find("body").insert(0, freejoint)
     print("Added floating_base_joint to first body element")
 
 
-def add_imu_site_and_sensors(xml_file_path: Path, imu: dict) -> None:
-    """Add an IMU <site> on the root body plus the base-state <sensor>s.
-
-    A floating-base locomotion sim needs, at the base:
-      - orientation / angular velocity / linear acceleration -> surfaced to
-        ros2_control's MujocoSystem as the ``<prefix>_imu`` sensor (from MJCF
-        ``<prefix>_quat``/``_gyro``/``_accel``), republished by
-        imu_sensor_broadcaster as sensor_msgs/Imu on /imu/data;
-      - body-frame linear velocity -> ``<prefix>_vel`` velocimeter, read by the
-        base-velocity MuJoCo physics plugin (the RL policy's ``base_lin_vel``
-        obs term; a state estimator supplies it on hardware).
-    A ``framepos`` is emitted too so mujoco_ros2_control's framepos/framequat
-    Odometry publisher (keyed by site name) is well-formed.
-
-    A <site> is mandatory: mujoco_ros2_control resolves every sensor's site via
-    ``mj_id2name(mjOBJ_SITE, ...)`` and SIGABRTs on a siteless model (see
-    add_actuators). Emitted only for floating-base variants (config-gated), so
-    the fixed-base ros2_control variants stay sensor-free.
+def add_imu_site_and_sensors(root: ET.Element, imu: dict) -> None:
+    """Add an IMU ``<site>`` on the root body plus the base-state sensors.
+
+    A floating-base locomotion sim needs two things at the base. Orientation, angular
+    velocity and linear acceleration reach ros2_control's MujocoSystem as the
+    ``<prefix>_imu`` sensor, built from the MJCF ``_quat``, ``_gyro`` and ``_accel``
+    sensors, and imu_sensor_broadcaster republishes them as sensor_msgs/Imu on /imu/data.
+    Body-frame linear velocity comes from the ``<prefix>_vel`` velocimeter, which the
+    base-velocity MuJoCo physics plugin reads for the RL policy's ``base_lin_vel`` obs
+    term. A state estimator supplies that term on hardware.
+
+    A ``framepos`` is emitted as well, so mujoco_ros2_control's framepos/framequat
+    Odometry publisher, which is keyed by site name, is well-formed.
+
+    The ``<site>`` is mandatory: mujoco_ros2_control resolves every sensor's site through
+    ``mj_id2name(mjOBJ_SITE, ...)`` and aborts on a siteless model. See add_actuators.
+    physics.json gates this block, so the fixed-base variants stay sensor-free.
     """
     site_name = imu.get("site", "imu_site")
     prefix = imu.get("prefix", "base")
-    pos = imu.get("pos", [0.0, 0.0, 0.0])
-
-    tree = ET.parse(xml_file_path)
-    root = tree.getroot()
-    worldbody = root.find("worldbody")
-    first_body = worldbody.find("body") if worldbody is not None else None
-    if first_body is None:
-        print("No body element found in worldbody; skipping IMU site")
-        return
 
+    body = root.find("worldbody").find("body")
     site = ET.Element("site")
     site.set("name", site_name)
-    site.set("pos", " ".join(str(v) for v in pos))
-    # Keep a leading freejoint (if any) as the body's first child.
-    lead = 1 if (len(first_body) and first_body[0].tag == "joint"
-                 and first_body[0].get("type") == "free") else 0
-    first_body.insert(lead, site)
-
-    sensor_section = ensure_section(root, "sensor", before_tag_name="actuator")
-    # IMU triad (consumed by MujocoSystem's <prefix>_imu sensor), then the
-    # velocimeter (base linear velocity) and a framepos (odom completeness).
-    quat = ET.SubElement(sensor_section, "framequat")
-    quat.set("name", f"{prefix}_quat")
-    quat.set("objtype", "site")
-    quat.set("objname", site_name)
-    gyro = ET.SubElement(sensor_section, "gyro")
-    gyro.set("name", f"{prefix}_gyro")
-    gyro.set("site", site_name)
-    accel = ET.SubElement(sensor_section, "accelerometer")
-    accel.set("name", f"{prefix}_accel")
-    accel.set("site", site_name)
-    vel = ET.SubElement(sensor_section, "velocimeter")
-    vel.set("name", f"{prefix}_vel")
-    vel.set("site", site_name)
-    fpos = ET.SubElement(sensor_section, "framepos")
-    fpos.set("name", f"{prefix}_pos")
-    fpos.set("objtype", "site")
-    fpos.set("objname", site_name)
-
-    tree.write(xml_file_path, encoding="utf-8", xml_declaration=True)
+    site.set("pos", " ".join(str(v) for v in imu.get("pos", [0.0, 0.0, 0.0])))
+    # Keep a leading freejoint, if there is one, as the body's first child.
+    lead = 1 if len(body) and body[0].tag == "joint" and body[0].get("type") == "free" else 0
+    body.insert(lead, site)
+
+    # The IMU triad that MujocoSystem reads, then the velocimeter (base linear velocity)
+    # and a framepos (odom completeness).
+    section = _section(root, "sensor", before="actuator")
+    for tag, suffix, attributes in (
+        ("framequat", "quat", {"objtype": "site", "objname": site_name}),
+        ("gyro", "gyro", {"site": site_name}),
+        ("accelerometer", "accel", {"site": site_name}),
+        ("velocimeter", "vel", {"site": site_name}),
+        ("framepos", "pos", {"objtype": "site", "objname": site_name}),
+    ):
+        ET.SubElement(section, tag, {"name": f"{prefix}_{suffix}", **attributes})
+    _indent_section(root, section)
     print(f"Added IMU site '{site_name}' + {prefix}_quat/gyro/accel/vel/pos sensors")
 
 
-def patch_contacts(xml_file_path: Path, contact: dict) -> None:
+def patch_contacts(root: ET.Element, contact: dict) -> None:
     """Match mjlab's contact model for a legged robot.
 
-    mjlab's ``patch_spec`` defaults every collision geom to ``condim=1``
-    (frictionless point contact) and then re-promotes only the foot geoms to
-    ``condim=3`` + friction + priority. This means the feet grip the ground while
-    a grazing shin/thigh/self-contact SLIDES instead of catching -- important for
-    a floating-base gait. Our stock MJCF leaves every collision geom at MuJoCo's
-    default ``condim=3`` + friction, so a leg capsule that brushes the ground (or
-    the other leg) grabs and can trip the robot.
-
-    Config (physics.json ``contact``): ``foot_bodies`` (bodies whose collision
-    geoms keep friction), ``foot_friction`` (slide coefficient), ``default_condim``
-    (everything else; 1 = frictionless). Higher ``priority`` on the feet makes the
-    foot friction win over the floor's in the contact pair.
+    mjlab's ``patch_spec`` defaults every collision geom to ``condim=1``, a frictionless
+    point contact, and then re-promotes only the foot geoms to ``condim=3`` with friction
+    and priority. The feet therefore grip the ground while a grazing shin, thigh or
+    self-contact slides instead of catching, which matters for a floating-base gait. Our
+    stock MJCF leaves every collision geom at MuJoCo's default ``condim=3`` with friction,
+    so a leg capsule that brushes the ground or the other leg grabs and can trip the robot.
+
+    physics.json's ``contact`` block configures this. ``foot_bodies`` lists the bodies
+    whose collision geoms keep friction, ``foot_friction`` is the slide coefficient, and
+    ``default_condim`` applies to everything else, where 1 means frictionless. The higher
+    ``priority`` on the feet makes the foot friction win over the floor's in the pair.
     """
     foot_bodies = set(contact.get("foot_bodies", ()))
     foot_friction = contact.get("foot_friction", 1.0)
     default_condim = str(int(contact.get("default_condim", 1)))
-    foot_friction_str = f"{foot_friction} 0.005 0.0001"  # slide torsional rolling
-
-    tree = ET.parse(xml_file_path)
-    root = tree.getroot()
-    worldbody = root.find("worldbody")
-    if worldbody is None:
-        return
-
-    def is_collision(geom: ET.Element) -> bool:
-        return geom.get("contype", "1") != "0" or geom.get("conaffinity", "1") != "0"
-
-    n_foot = 0
-    n_other = 0
+    counts = {"foot": 0, "other": 0}
 
     def walk(body: ET.Element, in_foot: bool) -> None:
-        nonlocal n_foot, n_other
-        foot = in_foot or (body.get("name") in foot_bodies)
-        # Name collision geoms <body>_collision_<i>. MuJoCo leaves URDF-imported
-        # geoms anonymous, but the training env selects them BY NAME -- mjlab's
-        # friction DR matches r"^(left|right)_foot_collision_\d+$" -- and an
-        # unnamed geom can never match, so the randomization would silently do
-        # nothing. Only fills blanks; an explicit name in the MJCF wins.
-        collision_index = 0
+        is_foot = in_foot or body.get("name") in foot_bodies
+        # Name collision geoms <body>_collision_<i>. MuJoCo leaves URDF-imported geoms
+        # anonymous, but the training env selects them BY NAME -- mjlab's friction
+        # randomization matches r"^(left|right)_foot_collision_\d+$" -- and an unnamed
+        # geom can never match, so the randomization would silently do nothing. This only
+        # fills blanks: an explicit name in the MJCF wins.
+        index = 0
         for geom in body.findall("geom"):
-            if not is_collision(geom):
+            if geom.get("contype", "1") == "0" and geom.get("conaffinity", "1") == "0":
                 continue
             if not geom.get("name"):
-                geom.set("name", f"{body.get('name')}_collision_{collision_index}")
-            collision_index += 1
-            if foot:
+                geom.set("name", f"{body.get('name')}_collision_{index}")
+            index += 1
+            if is_foot:
                 geom.set("condim", "3")
-                geom.set("friction", foot_friction_str)
+                geom.set("friction", f"{foot_friction} 0.005 0.0001")  # slide torsion roll
                 geom.set("priority", "1")
-                n_foot += 1
             else:
                 geom.set("condim", default_condim)
-                n_other += 1
+            counts["foot" if is_foot else "other"] += 1
         for child in body.findall("body"):
-            walk(child, foot)
+            walk(child, is_foot)
 
-    for body in worldbody.findall("body"):
+    for body in root.find("worldbody").findall("body"):
         walk(body, False)
 
-    tree.write(xml_file_path, encoding="utf-8", xml_declaration=True)
     print(
-        f"Patched contacts: {n_foot} foot geom(s) condim=3 friction={foot_friction} "
-        f"priority=1 (bodies {sorted(foot_bodies)}); {n_other} other geom(s) condim={default_condim}"
+        f"Patched contacts: {counts['foot']} foot geom(s) condim=3 friction={foot_friction} "
+        f"priority=1 (bodies {sorted(foot_bodies)}); "
+        f"{counts['other']} other geom(s) condim={default_condim}"
     )
 
 
-def apply_joint_properties(xml_file_path: Path, joint_properties: dict) -> None:
-    tree = ET.parse(xml_file_path)
-    root = tree.getroot()
-
+def apply_joint_properties(root: ET.Element, joint_properties: dict) -> None:
+    """Set frictionloss and armature on every non-free joint."""
     for joint in root.iter("joint"):
-        joint_name = joint.get("name")
-        if not joint_name or joint.get("type") == "free":
+        name = joint.get("name")
+        if not name or joint.get("type") == "free":
             continue
-        joint_config = resolve_joint_properties(joint_name, joint_properties)
-        joint.set("frictionloss", str(require_joint_attribute(joint_name, joint_config, "friction_loss")))
-        joint.set("armature", str(require_joint_attribute(joint_name, joint_config, "armature")))
-
-    tree.write(xml_file_path, encoding="utf-8", xml_declaration=True)
-
-
-def replace_cylinders_with_capsules(xml_file_path: Path) -> int:
-    tree = ET.parse(xml_file_path)
-    root = tree.getroot()
-
-    count = 0
-    for geom in root.iter("geom"):
-        if geom.get("type") == "cylinder":
-            geom.set("type", "capsule")
-            count += 1
-
-    if count:
-        tree.write(xml_file_path, encoding="utf-8", xml_declaration=True)
-    return count
+        joint.set("frictionloss", str(_joint_property(name, joint_properties, "friction_loss")))
+        joint.set("armature", str(_joint_property(name, joint_properties, "armature")))
 
 
 # ---------------------------------------------------------------------------
-# Orchestration
+# Driver
 # ---------------------------------------------------------------------------
 
 
-def convert(
-    urdf_path: Path,
-    output_xml_path: Path,
-    joint_properties: dict,
-    *,
-    meshes_dir: Path,
-    out_meshdir: str = "../meshes/visual/",
-    physics_options: dict | None = None,
-    freejoint: bool = False,
-    imu: dict | None = None,
-    contact: dict | None = None,
-    notice: str | None = None,
-) -> Path:
-    urdf_path = Path(urdf_path)
-    output_xml_path = Path(output_xml_path)
-    meshes_dir = Path(meshes_dir)
-    output_xml_path.parent.mkdir(parents=True, exist_ok=True)
-
-    with tempfile.TemporaryDirectory(prefix="rd_mjcf_") as tmp:
-        temp_urdf = Path(tmp) / urdf_path.name
-        # Rewrite mesh refs to bare basenames so compilation resolves them via meshdir,
-        # independent of the raw URDF's own relative paths.
-        tree = robot_model.parse(urdf_path)
-        robot_model.rewrite_mesh_filenames(tree.getroot(), lambda name: name)
-        tree.write(temp_urdf, encoding="utf-8", xml_declaration=True)
-        add_mujoco_compiler_tag(temp_urdf, meshdir=str(meshes_dir.resolve()))
-
-        temp_xml = Path(tmp) / "mjmodel.xml"
-        save_mjcf_from_urdf(temp_urdf, temp_xml)
-
-        if freejoint:
-            add_freejoint(temp_xml)
-        replaced = replace_cylinders_with_capsules(temp_xml)
-        if replaced:
-            print(f"Replaced {replaced} cylinder geom(s) with capsules")
-        add_option_tag(temp_xml, physics_options or {})
-        add_actuators(temp_xml, joint_properties)
-        if imu:
-            add_imu_site_and_sensors(temp_xml, imu)
-        if contact:
-            patch_contacts(temp_xml, contact)
-        apply_joint_properties(temp_xml, joint_properties)
-        set_compiler_meshdir(temp_xml, out_meshdir)
-
-        output_xml_path.write_text(temp_xml.read_text())
-
-    if notice:
-        prepend_comment(output_xml_path, notice)
-
-    return output_xml_path
-
-
-def generate(robot_dir: Path, *, freejoint: bool = False) -> list[Path]:
-    """Generate mjcf/<robot>.xml for a robots/<robot>/ directory."""
-    robot_dir = Path(robot_dir)
+def generate(robot_dir: Path) -> list[Path]:
+    """Write mjcf/<robot>.xml for one ``robots/<robot>/`` directory."""
     robot = robot_dir.name
     cad_dir = robot_dir / "cad"
-    hub_urdf = robot_dir / "urdf" / f"{robot}.urdf"
     joint_properties = json.loads((cad_dir / "joint_properties.json").read_text())
+
     physics_path = cad_dir / "physics.json"
-    physics_options = json.loads(physics_path.read_text()) if physics_path.exists() else {}
-    # Floating-base + IMU are opt-in per variant via physics.json. Pop them out
-    # of physics_options so they don't leak into the MuJoCo <option> tag.
-    freejoint = bool(physics_options.pop("freejoint", False)) or freejoint
-    imu = physics_options.pop("imu", None)
-    contact = physics_options.pop("contact", None)
-    mjcf_path = convert(
-        hub_urdf,
-        robot_dir / "mjcf" / f"{robot}.xml",
-        joint_properties,
-        meshes_dir=robot_dir / "meshes" / "visual",
-        physics_options=physics_options,
-        freejoint=freejoint,
-        imu=imu,
-        contact=contact,
-        notice=robot_model.autogen_comment(robot),
-    )
+    options = json.loads(physics_path.read_text()) if physics_path.exists() else {}
+    # Floating base, IMU and contact are per-variant opt-ins. Pop them so they do not
+    # leak into the MuJoCo <option> tag.
+    freejoint = options.pop("freejoint", False)
+    imu = options.pop("imu", None)
+    contact = options.pop("contact", None)
+
+    with tempfile.TemporaryDirectory(prefix="robot_assets_mjcf_") as tmp:
+        root = compile_mjcf(
+            robot_dir / "urdf" / f"{robot}.urdf",
+            robot_dir / "meshes" / "visual",
+            Path(tmp),
+        )
+
+    if freejoint:
+        add_freejoint(root)
+    replaced = replace_cylinders_with_capsules(root)
+    if replaced:
+        print(f"Replaced {replaced} cylinder geom(s) with capsules")
+    add_option(root, options)
+    add_actuators(root, joint_properties)
+    if imu:
+        add_imu_site_and_sensors(root, imu)
+    if contact:
+        patch_contacts(root, contact)
+    apply_joint_properties(root, joint_properties)
+
+    root.find("compiler").set("meshdir", MESHDIR)
+    banner = ET.Comment(robot_model.autogen_comment(robot))
+    banner.tail = "\n" + INDENT
+    root.insert(0, banner)
+
+    mjcf_path = robot_dir / "mjcf" / f"{robot}.xml"
+    mjcf_path.parent.mkdir(parents=True, exist_ok=True)
+    ET.ElementTree(root).write(mjcf_path, encoding="utf-8", xml_declaration=True)
     return [mjcf_path]
 
 
 def main(argv: list[str] | None = None) -> None:
     parser = argparse.ArgumentParser(description="Generate mjcf/<robot>.xml for a robot.")
     parser.add_argument("robot", help="Robot name (under ./robots/) or a path to a robot dir.")
-    parser.add_argument("--freejoint", action="store_true", help="Add a free joint under the first body.")
     args = parser.parse_args(argv)
-    for path in generate(robot_model.resolve_robot_dir(args.robot), freejoint=args.freejoint):
+    for path in generate(robot_model.resolve_robot_dir(args.robot)):
         print(f"Wrote {path}")
 
 
diff --git a/robot_assets/workflow/urdf_to_xacro.py b/robot_assets/workflow/urdf_to_xacro.py
index 65c963f..48411a9 100644
--- a/robot_assets/workflow/urdf_to_xacro.py
+++ b/robot_assets/workflow/urdf_to_xacro.py
@@ -1,40 +1,95 @@
-"""Generate the ROS 2 xacro artifacts for a robot from its raw URDF + ros2_control.json.
-
-Emits three files into ``<robot_dir>/xacro/`` (the ``ros2_control_demos`` convention:
-a reusable model macro + a separate ``*.ros2_control.xacro`` + a thin top assembly):
-
-* ``<robot>.description.xacro``  -- ``<xacro:macro name="<robot>_description">`` wrapping
-  the CAD kinematics: a ``base_link`` root, ``${mesh_root}``-parameterised mesh paths
-  (default ``package://``), effort limits harmonised to ``joint_properties.json``.
-* ``<robot>.ros2_control.xacro`` -- the hardware macros: a per-joint MIT-mode interface
-  macro, per-group joint macros, a combined block (sim/mock) and per-bus blocks (real),
-  and a top dispatch macro that selects the backend via ``use_sim``/``use_fake_hardware``.
-* ``<robot>.urdf.xacro``         -- top assembly: declares args, includes + instantiates
-  the two macros above.
-
-All `${...}` are xacro expressions written as ``${{...}}`` inside f-strings (the doubled
-braces collapse to single braces at format time); ``$(arg ...)`` / ``$(find ...)`` use
-parentheses and need no escaping. Limits (lower/upper) are read from the URDF, never
-re-declared in ros2_control.json.
+"""Generate the ROS 2 xacro artifacts for a robot from its URDF hub and ros2_control.json.
+
+Writes three files into ``<robot_dir>/xacro/``, following the ``ros2_control_demos``
+split of a reusable model macro, a separate hardware file, and a thin assembly:
+
+* ``<robot>.description.xacro``  -- ``<xacro:macro name="<robot>_description">`` around the
+  CAD kinematics: a ``base_link`` root, ``${mesh_root}``-parameterised mesh paths, effort
+  limits harmonised to ``joint_properties.json``.
+* ``<robot>.ros2_control.xacro`` -- the hardware macros: a joint macro, per-group joint
+  macros, one combined block for the mock and MuJoCo backends, per-bus blocks for real
+  hardware, and a top macro that dispatches between them.
+* ``<robot>.urdf.xacro``         -- the assembly: declares the args, includes the two
+  macros above and instantiates them.
+
+Backend selection follows the Universal Robots description convention: one boolean per
+non-real backend (``use_mock_hardware``, ``sim_mujoco``), real hardware as the fallback
+when both are false. The switches reach only the ``<hardware>`` plugin choice. Joint
+macros are backend-agnostic and always emit their hardware params, because every backend
+ignores the params it does not know.
+
+Every ``${...}`` below is a xacro expression, written ``${{...}}`` inside an f-string.
+``$(arg ...)`` and ``$(find ...)`` use parentheses and need no escaping. Position limits
+come from the URDF and are never re-declared in ros2_control.json.
 """
 
 import argparse
 import json
 from pathlib import Path
-import textwrap
 import xml.etree.ElementTree as ET
 
 from . import robot_model
 
 DEFAULT_PACKAGE = robot_model.DEFAULT_PACKAGE
 
+# Backend-switch args. Both false selects real hardware.
+MOCK_ARG = "use_mock_hardware"
+SIM_ARG = "sim_mujoco"
+
+# State interfaces of an IMU, in the order imu_sensor_broadcaster expects.
+IMU_STATE_INTERFACES = (
+    "orientation.x", "orientation.y", "orientation.z", "orientation.w",
+    "angular_velocity.x", "angular_velocity.y", "angular_velocity.z",
+    "linear_acceleration.x", "linear_acceleration.y", "linear_acceleration.z",
+)
+
+# Four-bar geometry a joint declares under ``linkage`` in ros2_control.json. The four
+# lengths share one unit, ``alpha_zero`` is in degrees and ``sign`` is +1 or -1. All six
+# are required: humanoid_devices_robstride rejects a partial set, and its defaults for
+# the last two would otherwise apply silently.
+LINKAGE_KEYS = ("ground", "crank_in", "coupler", "crank_out", "alpha_zero", "sign")
+
+MAX_LINE = 100
+
+
 def _banner(robot: str) -> str:
-    """The generated-asset banner as a literal XML comment (xacro files are string-built)."""
+    """Return the generated-asset banner as a literal XML comment."""
     return f"<!--{robot_model.autogen_comment(robot)}-->"
 
-# Standard backend-switch arg names (franka_ros2 / Universal_Robots convention).
-SIM_ARG = "use_sim"
-MOCK_ARG = "use_fake_hardware"
+
+def _pack(tokens: list[str], indent: str) -> str:
+    """Join tokens into ``MAX_LINE``-wide lines, hanging-indented by ``indent``.
+
+    The budget leaves two columns for the tag's closing ``">`` or ``/>``.
+    """
+    lines: list[list[str]] = [[]]
+    for token in tokens:
+        if lines[-1] and len(indent) + len(" ".join(lines[-1] + [token])) > MAX_LINE - 2:
+            lines.append([])
+        lines[-1].append(token)
+    return ("\n" + indent).join(" ".join(line) for line in lines)
+
+
+def _macro_open(name: str, params: list[str]) -> str:
+    """Return a ``<xacro:macro>`` opening tag, wrapping a long parameter list."""
+    head = f'  <xacro:macro name="{name}"'
+    if not params:
+        return f"{head}>"
+    single = f'{head} params="{" ".join(params)}">'
+    if len(single) <= MAX_LINE:
+        return single
+    # Wrapped form puts params= under name=, and its continuations under the open quote.
+    head_indent = " " * len("  <xacro:macro ")
+    body_indent = head_indent + " " * len('params="')
+    return f'{head}\n{head_indent}params="{_pack(params, body_indent)}">'
+
+
+def _sensor_element(name: str, indent: str) -> str:
+    """Return a ros2_control ``<sensor>`` carrying the IMU state interfaces."""
+    interfaces = "\n".join(
+        f'{indent}  <state_interface name="{n}"/>' for n in IMU_STATE_INTERFACES
+    )
+    return f'{indent}<sensor name="{name}">\n{interfaces}\n{indent}</sensor>'
 
 
 # ---------------------------------------------------------------------------
@@ -49,27 +104,26 @@ def build_description_xacro(
     base_link: dict,
     package: str = DEFAULT_PACKAGE,
 ) -> str:
-    tree = robot_model.parse(urdf_path)
-    root = tree.getroot()
-
+    """Return the description xacro: the CAD kinematics wrapped in a reusable macro."""
+    root = robot_model.parse(urdf_path).getroot()
     robot_model.harmonize_effort(root, joint_properties)
     robot_model.rewrite_mesh_filenames(root, lambda name: f"${{mesh_root}}/{name}")
-    child = base_link.get("child") or robot_model.root_link(root)
-    robot_model.inject_base_link(root, base_link.get("name", "base_link"), child)
+    robot_model.inject_base_link(root, base_link["name"], base_link["child"])
 
-    mesh_root_default = f"package://{package}/robots/{robot}/meshes/visual"
     ET.register_namespace("xacro", robot_model.XACRO_NS)
     out_root = ET.Element("robot")
     macro = ET.SubElement(
         out_root,
         f"{{{robot_model.XACRO_NS}}}macro",
-        {"name": f"{robot}_description", "params": f"mesh_root:={mesh_root_default}"},
+        {
+            "name": f"{robot}_description",
+            "params": f"mesh_root:=package://{package}/robots/{robot}/meshes/visual",
+        },
     )
     for element in list(root):
         macro.append(element)
 
-    body = robot_model.to_string(out_root)
-    return f'<?xml version="1.0"?>\n{_banner(robot)}\n{body}\n'
+    return f'<?xml version="1.0"?>\n{_banner(robot)}\n{robot_model.to_string(out_root)}\n'
 
 
 # ---------------------------------------------------------------------------
@@ -77,530 +131,203 @@ def build_description_xacro(
 # ---------------------------------------------------------------------------
 
 
-_LINKAGE_PARAM_BLOCK = """        <!-- Four-bar transmission geometry, for joints that declare one in
-             ros2_control.json. The geometry is a PHYSICAL FACT so it is always
-             published: calibrate_robot reads it from /robot_description to refer
-             the URDF joint limits into actuator space, even on the runs where the
-             hardware plugin must NOT apply the transform. `linkage_enabled`
-             (= the use_linkage arg) is what switches the plugin's behaviour:
-             false during calibration, which needs raw actuator angles. With it
-             true, RobstrideSystem converts joint<->actuator through the linkage
-             and refers the commanded impedance by J^2, so /joint_states and every
-             controller speak true joint space. -->
-        <xacro:if value="${linkage_ground > 0}">
-          <param name="linkage_ground">${linkage_ground}</param>
-          <param name="linkage_crank_in">${linkage_crank_in}</param>
-          <param name="linkage_coupler">${linkage_coupler}</param>
-          <param name="linkage_crank_out">${linkage_crank_out}</param>
-          <param name="linkage_alpha_zero">${linkage_alpha_zero}</param>
-          <param name="linkage_sign">${linkage_sign}</param>
-          <param name="linkage_enabled">${use_linkage}</param>
-        </xacro:if>
-"""
-
-def _joint_macro(robot: str, command: list[str], state: list[str],
-                 any_linkage: bool = False) -> str:
-    cmd_lines = "\n".join(f'      <command_interface name="{n}"/>' for n in command)
-    state_lines = "\n".join(f'      <state_interface name="{n}"/>' for n in state)
-    # The four-bar params/section only appear for robots that declare a linkage,
-    # so every other robot regenerates byte-identically.
-    link_params = ("""
-                       use_linkage:=true linkage_ground:=0
-                       linkage_crank_in:=0 linkage_coupler:=0 linkage_crank_out:=0
-                       linkage_alpha_zero:=0 linkage_sign:=1""" if any_linkage else "")
-    link_block = _LINKAGE_PARAM_BLOCK if any_linkage else ""
-    return f"""  <!-- One joint: {len(command)} command + {len(state)} state interfaces (MIT mode).
-       Real-only hardware params are emitted under xacro:unless (sim/mock ignore them). -->
-  <xacro:macro name="{robot}_joint"
-               params="name can_id model direction
-                       lower_limit upper_limit torque_limit current_limit
-                       use_fake_hardware use_sim{link_params}">
+def _joint_macro(robot: str, command: list[str], state: list[str], linkage: bool) -> str:
+    """Return one joint macro. With ``linkage``, it also carries the four-bar params."""
+    lines = [f'      <command_interface name="{n}"/>' for n in command]
+    lines += [f'      <state_interface name="{n}"/>' for n in state]
+    interfaces = "\n".join(lines)
+    # (macro param, emitted <param> name). They differ only for use_linkage, whose
+    # plugin-side spelling is linkage_enabled.
+    hardware = [(p, p) for p in ("can_id", "model", "direction",
+                                 "lower_limit", "upper_limit", "torque_limit", "current_limit")]
+    if linkage:
+        hardware += [(f"linkage_{key}", f"linkage_{key}") for key in LINKAGE_KEYS]
+        hardware += [("use_linkage", "linkage_enabled")]
+        header = f"""  <!-- A joint driven through a four-bar linkage, otherwise identical to
+       {robot}_joint. The geometry is a physical fact, so it is always published:
+       calibrate_robot reads it from /robot_description to refer the URDF joint limits into
+       actuator space even on the runs where the plugin must not apply the transform.
+       linkage_enabled is the switch for that. With it true, RobstrideSystem converts
+       joint<->actuator through the linkage and refers the commanded impedance by J^2, so
+       /joint_states and every controller speak true joint space. Calibration sets it
+       false, because it needs raw actuator angles. -->"""
+    else:
+        header = f"""  <!-- One joint: {len(command)} command + {len(state)} state interfaces (MIT mode).
+       The params are read by humanoid_devices_robstride. The mock and MuJoCo backends
+       ignore params they do not know, so this one macro serves all three. -->"""
+
+    name = f"{robot}_linkage_joint" if linkage else f"{robot}_joint"
+    params = ["name", *(param for param, _ in hardware)]
+    body = "\n".join(
+        f'      <param name="{emitted}">${{{param}}}</param>' for param, emitted in hardware
+    )
+    return f"""{header}
+{_macro_open(name, params)}
     <joint name="${{name}}">
-{cmd_lines}
-{state_lines}
-      <xacro:unless value="${{use_sim or use_fake_hardware}}">
-        <param name="can_id">${{can_id}}</param>
-        <param name="model">${{model}}</param>
-        <param name="direction">${{direction}}</param>
-        <param name="lower_limit">${{lower_limit}}</param>
-        <param name="upper_limit">${{upper_limit}}</param>
-        <param name="torque_limit">${{torque_limit}}</param>
-        <param name="current_limit">${{current_limit}}</param>
-{link_block}      </xacro:unless>
+{interfaces}
+{body}
     </joint>
   </xacro:macro>"""
 
 
-#: Four-bar transmission keys a joint may declare under ``linkage`` in
-#: ros2_control.json. Lengths must share one unit; ``alpha_zero`` is in DEGREES.
-_LINKAGE_KEYS = ("ground", "crank_in", "coupler", "crank_out", "alpha_zero", "sign")
-
-
 def _joint_call(robot: str, joint: dict, limits: dict) -> str:
-    limit = limits.get(joint["name"], {})
-    lower = limit.get("lower", 0.0)
-    upper = limit.get("upper", 0.0)
+    """Return one joint-macro instantiation, with position limits taken from the URDF."""
     linkage = joint.get("linkage")
-    extra = ""
+    macro = f"{robot}_linkage_joint" if linkage else f"{robot}_joint"
+    limit = limits[joint["name"]]
+    attributes = [
+        f'name="{joint["name"]}"',
+        f'can_id="{joint["can_id"]}"',
+        f'model="{joint["model"]}"',
+        f'direction="{joint["direction"]}"',
+        f'lower_limit="{limit["lower"]}"',
+        f'upper_limit="{limit["upper"]}"',
+        f'torque_limit="{joint["torque_limit"]}"',
+        f'current_limit="{joint["current_limit"]}"',
+    ]
     if linkage:
-        missing = [k for k in _LINKAGE_KEYS[:4] if k not in linkage]
+        missing = [key for key in LINKAGE_KEYS if key not in linkage]
         if missing:
             raise ValueError(
-                f'joint {joint["name"]!r}: linkage missing {missing}; all four '
-                f"lengths (ground/crank_in/coupler/crank_out) are required."
+                f"joint {joint['name']!r}: linkage is missing {missing}. "
+                f"Give all of {list(LINKAGE_KEYS)}."
             )
-        extra = (
-            f'\n                      linkage_ground="{linkage["ground"]}" '
-            f'linkage_crank_in="{linkage["crank_in"]}"\n'
-            f'                      linkage_coupler="{linkage["coupler"]}" '
-            f'linkage_crank_out="{linkage["crank_out"]}"\n'
-            f'                      linkage_alpha_zero="{linkage.get("alpha_zero", 0)}" '
-            f'linkage_sign="{linkage.get("sign", 1)}"'
-            f'\n                      use_linkage="${{use_linkage}}"'
-        )
-    return (
-        f'    <xacro:{robot}_joint name="{joint["name"]}" can_id="{joint["can_id"]}" '
-        f'model="{joint["model"]}" direction="{joint["direction"]}"\n'
-        f'                      lower_limit="{lower}" upper_limit="{upper}"\n'
-        f'                      torque_limit="{joint["torque_limit"]}" '
-        f'current_limit="{joint["current_limit"]}"\n'
-        f'                      use_fake_hardware="${{use_fake_hardware}}" '
-        f'use_sim="${{use_sim}}"{extra}/>'
-    )
+        attributes += [f'linkage_{key}="{linkage[key]}"' for key in LINKAGE_KEYS]
+        attributes.append('use_linkage="${use_linkage}"')
+
+    head = f"    <xacro:{macro} "
+    return f"{head}{_pack(attributes, ' ' * len(head))}/>"
 
 
 def _group_macro(robot: str, group: str, joints: list[dict], limits: dict) -> str:
-    if not joints:
-        return f"""  <!-- {group}: stub. Populate when the CAN ids / model codes are confirmed on hardware. -->
-  <xacro:macro name="{robot}_{group}_joints" params="use_fake_hardware use_sim">
-    <!-- TODO: {group} joint declarations land here. -->
-  </xacro:macro>"""
-    calls = "\n".join(_joint_call(robot, j, limits) for j in joints)
-    # use_linkage only becomes a param when a joint in this group declares a
-    # four-bar, so groups/robots without one regenerate byte-identically.
-    extra = " use_linkage:=true" if any(j.get("linkage") for j in joints) else ""
-    return f"""  <xacro:macro name="{robot}_{group}_joints" params="use_fake_hardware use_sim{extra}">
+    """Return the macro that instantiates every joint of one group."""
+    calls = "\n".join(_joint_call(robot, joint, limits) for joint in joints)
+    # use_linkage only becomes a param where a joint in this group declares a four-bar.
+    params = ["use_linkage:=true"] if any(j.get("linkage") for j in joints) else []
+    return f"""{_macro_open(f"{robot}_{group}_joints", params)}
 {calls}
   </xacro:macro>"""
 
 
-_IMU_STATE_INTERFACES = (
-    "orientation.x", "orientation.y", "orientation.z", "orientation.w",
-    "angular_velocity.x", "angular_velocity.y", "angular_velocity.z",
-    "linear_acceleration.x", "linear_acceleration.y", "linear_acceleration.z",
-)
-
-
-def _imu_sensor_block(imu: dict) -> str:
-    """A ros2_control <sensor> for the base IMU, emitted only under use_sim.
-
-    MujocoSystem backs these state interfaces from the MJCF
-    ``<name-without-_imu>_quat``/``_gyro``/``_accel`` sensors, and
-    imu_sensor_broadcaster republishes them as sensor_msgs/Imu. Guarded by
-    use_sim so the mock backend (no such MuJoCo sensor) is unaffected; real
-    hardware gets its IMU from a dedicated driver node, not ros2_control.
-    """
-    name = imu["name"]
-    ifaces = "\n".join(f'          <state_interface name="{n}"/>' for n in _IMU_STATE_INTERFACES)
-    return f"""      <xacro:if value="${{use_sim}}">
-        <sensor name="{name}">
-{ifaces}
-        </sensor>
-      </xacro:if>"""
-
-
-def _combined_macro(
-    robot: str, name: str, active_groups: list[dict], backends: dict, imu: dict | None = None
-) -> str:
-    group_calls = "\n".join(
-        f'      <xacro:{robot}_{g["name"]}_joints '
-        f'use_fake_hardware="${{use_fake_hardware}}" use_sim="${{use_sim}}"/>'
-        for g in active_groups
+def _combined_macro(robot: str, groups: list[dict], backends: dict, imu: dict | None) -> str:
+    """Return the single-block macro shared by the mock and MuJoCo backends."""
+    calls = "\n".join(f'      <xacro:{robot}_{g["name"]}_joints/>' for g in groups)
+    # Only MuJoCo backs the IMU state interfaces; mock_components has no source for them.
+    sensor = (
+        f'\n      <xacro:if value="${{{SIM_ARG}}}">\n'
+        f'{_sensor_element(imu["name"], "        ")}\n      </xacro:if>'
+        if imu else ""
     )
-    imu_block = ("\n" + _imu_sensor_block(imu)) if imu else ""
-    return f"""  <!-- Combined single-block layout for the sim and mock backends. -->
-  <xacro:macro name="{robot}_ros2_control_combined" params="name use_fake_hardware use_sim">
+    return f"""  <!-- Combined single block for the mock and MuJoCo backends. -->
+{_macro_open(f"{robot}_ros2_control_combined", ["name", SIM_ARG])}
     <ros2_control name="${{name}}" type="system">
       <hardware>
-        <xacro:if value="${{use_sim}}">
+        <xacro:if value="${{{SIM_ARG}}}">
           <plugin>{backends["sim"]}</plugin>
         </xacro:if>
-        <xacro:unless value="${{use_sim}}">
+        <xacro:unless value="${{{SIM_ARG}}}">
           <plugin>{backends["mock"]}</plugin>
         </xacro:unless>
       </hardware>
-{group_calls}{imu_block}
+{calls}{sensor}
     </ros2_control>
   </xacro:macro>"""
 
 
-def _real_block(robot: str, group: dict, real_plugin: str, use_linkage: bool = False) -> str:
-    """One <ros2_control> bus block, indented as a direct child of the real macro."""
-    can_arg = group["can_interface_arg"]
-    link_arg = ' use_linkage="${use_linkage}"' if use_linkage else ""
-    return f"""    <ros2_control name="{group["block_name"]}" type="system">
+def _real_macro(
+    robot: str, groups: list[dict], params: list[str], backends: dict, imu: dict | None,
+    linkage_groups: set[str],
+) -> str:
+    """Return the real-hardware macro: one ``<ros2_control>`` block per CAN bus."""
+    blocks = []
+    for group in groups:
+        use_linkage = ' use_linkage="${use_linkage}"' if group["name"] in linkage_groups else ""
+        blocks.append(f"""    <ros2_control name="{group["block_name"]}" type="system">
       <hardware>
-        <plugin>{real_plugin}</plugin>
-        <param name="can_interface">${{{can_arg}}}</param>
+        <plugin>{backends["real"]}</plugin>
+        <param name="can_interface">${{{group["can_interface_arg"]}}}</param>
         <param name="calibration_file">${{calibration_file}}</param>
       </hardware>
-      <xacro:{robot}_{group["name"]}_joints use_fake_hardware="false" use_sim="false"{link_arg}/>
-    </ros2_control>"""
-
-
-def _real_imu_block(imu: dict) -> str:
-    """A standalone <ros2_control type="sensor"> block for the real base IMU.
-
-    Unlike the sim sensor (backed by MujocoSystem inside the combined block),
-    the real IMU is its own hardware component reading a USB-serial driver on
-    ``imu_port``. It exports the SAME state interfaces as the sim sensor, so
-    imu_sensor_broadcaster republishes /imu/data identically on sim and real
-    (no standalone driver node). Emitted only when ros2_control.json's ``imu``
-    carries a ``real_plugin``.
-    """
-    name = imu["name"]
-    block_name = imu.get("real_block_name", "BaseIMU")
-    ifaces = "\n".join(f'        <state_interface name="{n}"/>' for n in _IMU_STATE_INTERFACES)
-    return f"""    <ros2_control name="{block_name}" type="sensor">
+      <xacro:{robot}_{group["name"]}_joints{use_linkage}/>
+    </ros2_control>""")
+    # An IMU without a real_plugin exists only in sim, backed by MujocoSystem inside the
+    # combined block, so real hardware gets no sensor component for it.
+    if imu and imu.get("real_plugin"):
+        blocks.append(f"""    <ros2_control name="{imu["real_block_name"]}" type="sensor">
       <hardware>
         <plugin>{imu["real_plugin"]}</plugin>
         <param name="port">${{imu_port}}</param>
       </hardware>
-      <sensor name="{name}">
-{ifaces}
-      </sensor>
-    </ros2_control>"""
-
-
-def _real_macro(robot: str, groups: list[dict], backends: dict, imu: dict | None = None,
-                joints_by_group: dict[str, list[dict]] | None = None) -> str:
-    real_plugin = backends["real"]
-    blocks = []
-    # Group descriptors carry no joints, so linkage presence comes from the
-    # joints-by-group map the caller built.
-    jbg = joints_by_group or {}
-    any_linkage = any(j.get("linkage") for js in jbg.values() for j in js)
-    for group in groups:
-        block = _real_block(
-            robot, group, real_plugin,
-            use_linkage=any(j.get("linkage") for j in jbg.get(group["name"], [])))
-        if group.get("stub"):
-            # Stub buses only exist in mode=arms_neck; nest the block inside the guard.
-            block = (
-                f"    <!-- {group['name']} bus: only with mode=arms_neck; "
-                f"stub until the actuators are wired. -->\n"
-                f"    <xacro:if value=\"${{mode == 'arms_neck'}}\">\n"
-                f"{textwrap.indent(block, '  ')}\n"
-                f"    </xacro:if>"
-            )
-        blocks.append(block)
-    real_imu = bool(imu and imu.get("real_plugin"))
-    if real_imu:
-        blocks.append(_real_imu_block(imu))
+{_sensor_element(imu["name"], "      ")}
+    </ros2_control>""")
     body = "\n".join(blocks)
-    # imu_port is only a macro param when a real IMU block references it.
-    params = "mode can_interface_left can_interface_right calibration_file"
-    if real_imu:
-        params += " imu_port"
-    if any_linkage:
-        params += " use_linkage"
-    # Keep the header comment byte-identical for non-IMU robots (only the IMU
-    # ones gain the "(plus the base IMU sensor)" note), so regenerating a robot
-    # without a real IMU produces no diff.
-    if real_imu:
-        header = (
-            "  <!-- Real hardware: one <ros2_control> block per CAN bus (plus the base IMU\n"
-            "       sensor). The controller_manager runs them concurrently and exposes a\n"
-            "       single flat joint list to controllers. -->")
-    else:
-        header = (
-            "  <!-- Real hardware: one <ros2_control> block per CAN bus. The controller_manager\n"
-            "       runs them concurrently and exposes a single flat joint list to controllers. -->")
-    return f"""{header}
-  <xacro:macro name="{robot}_ros2_control_real"
-               params="{params}">
+    return f"""  <!-- Real hardware: one <ros2_control> block per CAN bus. The controller_manager
+       runs them concurrently and exposes a single flat joint list to controllers. -->
+{_macro_open(f"{robot}_ros2_control_real", params)}
 {body}
   </xacro:macro>"""
 
 
-def _top_macro(robot: str, name: str, imu: dict | None = None,
-               any_linkage: bool = False) -> str:
-    real_imu = bool(imu and imu.get("real_plugin"))
-    imu_param = " imu_port" if real_imu else ""
-    imu_pass = "\n        imu_port=\"${imu_port}\"" if real_imu else ""
-    # use_linkage is only threaded when some joint declares a four-bar, so
-    # robots without one regenerate byte-identically.
-    link_param = " use_linkage" if any_linkage else ""
-    link_pass = "\n        use_linkage=\"${use_linkage}\"" if any_linkage else ""
-    return f"""  <!-- Top-level dispatch: combined block for sim/mock, per-bus blocks for real
-       (use_sim wins over use_fake_hardware, matching franka_ros2 / UR precedence). -->
-  <xacro:macro name="{robot}_ros2_control"
-               params="name use_fake_hardware use_sim mode
-                       can_interface_left can_interface_right calibration_file{imu_param}{link_param}">
-    <xacro:if value="${{use_sim or use_fake_hardware}}">
-      <xacro:{robot}_ros2_control_combined name="${{name}}"
-        use_fake_hardware="${{use_fake_hardware}}" use_sim="${{use_sim}}"/>
+def _top_macro(robot: str, args: list[str], real_params: list[str]) -> str:
+    """Return the top macro dispatching to the combined or the real block."""
+    forwarded = "\n".join(f'        {arg}="${{{arg}}}"' for arg in real_params)
+    return f"""  <!-- Backend dispatch, following the Universal Robots description convention: one
+       boolean per non-real backend, real hardware as the fallback when both are false.
+       {SIM_ARG} wins over {MOCK_ARG}. -->
+{_macro_open(f"{robot}_ros2_control", ["name", *args])}
+    <xacro:if value="${{{SIM_ARG} or {MOCK_ARG}}}">
+      <xacro:{robot}_ros2_control_combined name="${{name}}" {SIM_ARG}="${{{SIM_ARG}}}"/>
     </xacro:if>
-    <xacro:unless value="${{use_sim or use_fake_hardware}}">
-      <xacro:{robot}_ros2_control_real mode="${{mode}}"
-        can_interface_left="${{can_interface_left}}"
-        can_interface_right="${{can_interface_right}}"
-        calibration_file="${{calibration_file}}"{imu_pass}{link_pass}/>
-    </xacro:unless>
-  </xacro:macro>"""
-
-
-# ---------------------------------------------------------------------------
-# Hybrid layout: heterogeneous backends on one controller_manager
-# ---------------------------------------------------------------------------
-# Selected by ros2_control.json ``"layout": "hybrid"``. The default CAN layout
-# (above) assumes one MIT joint macro + per-CAN-bus blocks sharing one ``real``
-# plugin. The hybrid layout instead emits one <ros2_control> block PER GROUP, each
-# with its own plugin + hardware params, and recognizes two joint kinds:
-#   * ethercat : CiA402 servo on an EtherCAT ring -- position/effort + an
-#                <ec_module> with a per-joint slave_config; no can_id.
-#   * sito     : MIT motor on SocketCAN -- the MIT interface set + can_id/model/
-#                direction (read by humanoid_devices_sito).
-# Sim and mock still collapse to one combined MIT block so the shared controllers
-# (which claim the MIT surface) run unchanged. The ``args`` from ros2_control.json
-# drive the dispatch (master_id, sito_can_interface, backends, ec_control_frequency,
-# erob_config_dir) instead of the CAN layout's fixed mode / can_interface_*.
-
-
-def _hybrid_real_args(args: dict) -> list[str]:
-    """Args threaded to the real macro: everything but the sim/mock switches."""
-    return [k for k in args if k not in (SIM_ARG, MOCK_ARG)]
-
-
-def _interface_lines(command: list[str], state: list[str]) -> str:
-    cmd = "\n".join(f'      <command_interface name="{n}"/>' for n in command)
-    st = "\n".join(f'      <state_interface name="{n}"/>' for n in state)
-    return f"{cmd}\n{st}"
-
-
-def _hybrid_mit_joint_macro(robot: str, command: list[str], state: list[str]) -> str:
-    return f"""  <!-- MIT joint ({len(command)} command + {len(state)} state): the uniform
-       interface surface the sim/mock combined block exposes for every joint. -->
-  <xacro:macro name="{robot}_mit_joint" params="name">
-    <joint name="${{name}}">
-{_interface_lines(command, state)}
-    </joint>
-  </xacro:macro>"""
-
-
-def _hybrid_ec_joint_macro(robot: str) -> str:
-    return f"""  <!-- eRob joint on EtherCAT (CiA402 via EcCiA402Drive), CSP (mode 8). No
-       stiffness/damping interface: impedance is the drive's loop gains, set out of band
-       by SDO. slave_config is per-joint, generated from the calibration at launch. -->
-  <xacro:macro name="{robot}_ec_joint" params="name position erob_config_dir">
-    <joint name="${{name}}">
-      <command_interface name="position"/>
-      <command_interface name="velocity"/>
-      <command_interface name="effort"/>
-      <command_interface name="mode_of_operation"/>
-      <command_interface name="reset_fault"/>
-      <state_interface name="position"/>
-      <state_interface name="velocity"/>
-      <state_interface name="effort"/>
-      <state_interface name="mode_of_operation_display"/>
-      <ec_module name="Slave${{position}}">
-        <plugin>ethercat_generic_plugins/EcCiA402Drive</plugin>
-        <param name="alias">0</param>
-        <param name="position">${{position}}</param>
-        <param name="mode_of_operation">8</param>
-        <param name="slave_config">${{erob_config_dir}}/${{name}}.yaml</param>
-      </ec_module>
-    </joint>
-  </xacro:macro>"""
-
-
-def _hybrid_sito_joint_macro(robot: str, command: list[str], state: list[str]) -> str:
-    return f"""  <!-- Sito joint on SocketCAN (MIT mode). Same interface surface as the combined
-       block; can_id / model / direction are read by humanoid_devices_sito/SitoSystem. -->
-  <xacro:macro name="{robot}_sito_joint" params="name can_id model direction">
-    <joint name="${{name}}">
-{_interface_lines(command, state)}
-      <param name="can_id">${{can_id}}</param>
-      <param name="model">${{model}}</param>
-      <param name="direction">${{direction}}</param>
-    </joint>
-  </xacro:macro>"""
-
-
-def _hybrid_all_mit_macro(robot: str, joints: list[dict]) -> str:
-    calls = "\n".join(f'    <xacro:{robot}_mit_joint name="{j["name"]}"/>' for j in joints)
-    return f"""  <!-- Every joint as MIT, for the combined sim/mock block. -->
-  <xacro:macro name="{robot}_all_joints_mit">
-{calls}
-  </xacro:macro>"""
-
-
-def _hybrid_group_joints_macro(robot: str, group: dict, joints: list[dict]) -> str:
-    if group["kind"] == "ethercat":
-        calls = "\n".join(
-            f'    <xacro:{robot}_ec_joint name="{j["name"]}" position="{j["position"]}" '
-            f'erob_config_dir="${{erob_config_dir}}"/>'
-            for j in joints
-        )
-        return f"""  <xacro:macro name="{robot}_{group["name"]}_joints" params="erob_config_dir">
-{calls}
-  </xacro:macro>"""
-    calls = "\n".join(
-        f'    <xacro:{robot}_sito_joint name="{j["name"]}" can_id="{j["can_id"]}" '
-        f'model="{j["model"]}" direction="{j["direction"]}"/>'
-        for j in joints
-    )
-    return f"""  <xacro:macro name="{robot}_{group["name"]}_joints">
-{calls}
-  </xacro:macro>"""
-
-
-def _hybrid_combined_macro(robot: str, backends: dict) -> str:
-    return f"""  <!-- Combined single block for sim (MujocoSystem) and mock (GenericSystem),
-       exposing every joint with the MIT surface. -->
-  <xacro:macro name="{robot}_ros2_control_combined" params="name use_sim">
-    <ros2_control name="${{name}}" type="system">
-      <hardware>
-        <xacro:if value="${{use_sim}}">
-          <plugin>{backends["sim"]}</plugin>
-        </xacro:if>
-        <xacro:unless value="${{use_sim}}">
-          <plugin>{backends["mock"]}</plugin>
-        </xacro:unless>
-      </hardware>
-      <xacro:{robot}_all_joints_mit/>
-    </ros2_control>
-  </xacro:macro>"""
-
-
-def _hybrid_real_block(robot: str, group: dict) -> str:
-    hw = "\n".join(
-        f'          <param name="{k}">{v}</param>'
-        for k, v in group.get("hardware_params", {}).items()
-    )
-    if group["kind"] == "ethercat":
-        joints_call = (
-            f'        <xacro:{robot}_{group["name"]}_joints erob_config_dir="${{erob_config_dir}}"/>'
-        )
-    else:
-        joints_call = f'        <xacro:{robot}_{group["name"]}_joints/>'
-    block = f"""      <ros2_control name="{group["block_name"]}" type="system">
-        <hardware>
-          <plugin>{group["plugin"]}</plugin>
-{hw}
-        </hardware>
-{joints_call}
-      </ros2_control>"""
-    enable = group.get("enable_when")
-    if not enable:
-        return block
-    guard = " or ".join(f"backends == '{v}'" for v in enable)
-    return f"""    <xacro:if value="${{{guard}}}">
-{block}
-    </xacro:if>"""
-
-
-def _hybrid_real_macro(robot: str, cfg: dict) -> str:
-    params = " ".join(_hybrid_real_args(cfg["args"]))
-    blocks = "\n".join(_hybrid_real_block(robot, g) for g in cfg["groups"])
-    return f"""  <!-- Real hardware: one <ros2_control> block per group, each with its own plugin,
-       run concurrently in one controller_manager. Each block is gated by the `backends`
-       arg so a single bus can be brought up alone (e.g. for the Sito calibration sweep). -->
-  <xacro:macro name="{robot}_ros2_control_real" params="{params}">
-{blocks}
-  </xacro:macro>"""
-
-
-def _hybrid_top_macro(robot: str, cfg: dict) -> str:
-    top_params = " ".join(["name", *cfg["args"].keys()])
-    real_pass = "\n".join(f'        {a}="${{{a}}}"' for a in _hybrid_real_args(cfg["args"]))
-    return f"""  <!-- Top-level dispatch: combined block for sim/mock, per-group real blocks
-       otherwise (use_sim wins over use_fake_hardware, matching franka_ros2 / UR). -->
-  <xacro:macro name="{robot}_ros2_control" params="{top_params}">
-    <xacro:if value="${{use_sim or use_fake_hardware}}">
-      <xacro:{robot}_ros2_control_combined name="${{name}}" use_sim="${{use_sim}}"/>
-    </xacro:if>
-    <xacro:unless value="${{use_sim or use_fake_hardware}}">
+    <xacro:unless value="${{{SIM_ARG} or {MOCK_ARG}}}">
       <xacro:{robot}_ros2_control_real
-{real_pass}/>
+{forwarded}/>
     </xacro:unless>
   </xacro:macro>"""
 
 
-def _build_hybrid_ros2_control(robot: str, cfg: dict, limits: dict) -> str:
-    command = cfg["mit_interfaces"]["command"]
-    state = cfg["mit_interfaces"]["state"]
-    joints = cfg["joints"]
+def build_ros2_control_xacro(robot: str, ros2_control: dict, limits: dict) -> str:
+    """Return the hardware xacro: joint macros, group macros and the three block macros."""
     joints_by_group: dict[str, list[dict]] = {}
-    for joint in joints:
+    for joint in ros2_control["joints"]:
         joints_by_group.setdefault(joint["group"], []).append(joint)
+    linkage_groups = {
+        group for group, joints in joints_by_group.items()
+        if any(j.get("linkage") for j in joints)
+    }
+    empty = [g["name"] for g in ros2_control["groups"] if not joints_by_group.get(g["name"])]
+    if empty:
+        raise ValueError(
+            f"{robot}: groups {empty} declare a bus but list no joints. Give each group "
+            f"at least one joint, or drop the group."
+        )
 
-    parts = [
-        _hybrid_mit_joint_macro(robot, command, state),
-        _hybrid_ec_joint_macro(robot),
-        _hybrid_sito_joint_macro(robot, command, state),
-        _hybrid_all_mit_macro(robot, joints),
-    ]
-    for group in cfg["groups"]:
-        parts.append(_hybrid_group_joints_macro(robot, group, joints_by_group.get(group["name"], [])))
-    parts.append(_hybrid_combined_macro(robot, cfg["backends"]))
-    parts.append(_hybrid_real_macro(robot, cfg))
-    parts.append(_hybrid_top_macro(robot, cfg))
-
-    body = "\n\n".join(parts)
-    return (
-        f'<?xml version="1.0"?>\n{_banner(robot)}\n'
-        f'<robot xmlns:xacro="http://www.ros.org/wiki/xacro">\n\n{body}\n\n</robot>\n'
-    )
-
-
-def _build_hybrid_assembly(robot: str, cfg: dict, package: str) -> str:
-    args = cfg.get("args", {})
-    arg_decls = "\n".join(f'  <xacro:arg name="{k}" default="{v}"/>' for k, v in args.items())
-    name_attr = cfg.get("combined_block_name", f"{robot}_system")
-    instantiation = "\n".join(f'    {a}="$(arg {a})"' for a in args)
-    return f"""<?xml version="1.0"?>
-{_banner(robot)}
-<robot xmlns:xacro="http://www.ros.org/wiki/xacro" name="{robot}">
-{arg_decls}
-
-  <xacro:include filename="$(find {package})/robots/{robot}/xacro/{robot}.description.xacro"/>
-  <xacro:include filename="$(find {package})/robots/{robot}/xacro/{robot}.ros2_control.xacro"/>
-
-  <xacro:{robot}_description/>
-
-  <xacro:{robot}_ros2_control
-    name="{name_attr}"
-{instantiation}/>
-</robot>
-"""
-
-
-def build_ros2_control_xacro(robot: str, ros2_control: dict, limits: dict) -> str:
-    if ros2_control.get("layout") == "hybrid":
-        return _build_hybrid_ros2_control(robot, ros2_control, limits)
     command = ros2_control["interfaces"]["command"]
     state = ros2_control["interfaces"]["state"]
-    backends = ros2_control["backends"]
     groups = ros2_control["groups"]
-    combined_name = ros2_control.get("combined_block_name", f"{robot}_system")
-
-    joints_by_group: dict[str, list[dict]] = {}
-    for joint in ros2_control["joints"]:
-        joints_by_group.setdefault(joint["group"], []).append(joint)
-
-    active_groups = [g for g in groups if not g.get("stub") and joints_by_group.get(g["name"])]
-
-    any_linkage = any(j.get("linkage") for j in ros2_control["joints"])
-    parts = [_joint_macro(robot, command, state, any_linkage)]
-    for group in groups:
-        parts.append(_group_macro(robot, group["name"], joints_by_group.get(group["name"], []), limits))
     imu = ros2_control.get("imu")
-    parts.append(_combined_macro(robot, combined_name, active_groups, backends, imu))
-    parts.append(_real_macro(robot, groups, backends, imu, joints_by_group))
-    parts.append(_top_macro(
-        robot, combined_name, imu,
-        any_linkage=any(j.get("linkage") for j in ros2_control["joints"])))
+    args = list(ros2_control["args"])
+    # The real macro takes every arg except the backend switches, which only the top
+    # macro reads. An arg a robot does not have (imu_port, use_linkage) is absent
+    # everywhere, so ros2_control.json's `args` is the single source for both lists.
+    real_params = [a for a in args if a not in (MOCK_ARG, SIM_ARG)]
+    if linkage_groups and "use_linkage" not in real_params:
+        raise ValueError(
+            f"{robot}: joints in {sorted(linkage_groups)} declare a four-bar linkage, so "
+            f'ros2_control.json must declare a "use_linkage" arg.'
+        )
+
+    parts = [_joint_macro(robot, command, state, linkage=False)]
+    if linkage_groups:
+        parts.append(_joint_macro(robot, command, state, linkage=True))
+    parts += [
+        _group_macro(robot, group["name"], joints_by_group[group["name"]], limits)
+        for group in groups
+    ]
+    parts += [
+        _combined_macro(robot, groups, ros2_control["backends"], imu),
+        _real_macro(robot, groups, real_params, ros2_control["backends"], imu, linkage_groups),
+        _top_macro(robot, args, real_params),
+    ]
 
     body = "\n\n".join(parts)
     return (
@@ -615,48 +342,35 @@ def build_ros2_control_xacro(robot: str, ros2_control: dict, limits: dict) -> st
 
 
 def build_assembly_xacro(robot: str, ros2_control: dict | None, package: str = DEFAULT_PACKAGE) -> str:
-    """Top assembly. With a ros2_control spec it wires the hardware macro; without one
-    (model-only robots like the full lite) it just instantiates the model."""
-    if ros2_control and ros2_control.get("layout") == "hybrid":
-        return _build_hybrid_assembly(robot, ros2_control, package)
-    if not ros2_control:
+    """Return the assembly xacro. Without a ros2_control spec it emits the model alone."""
+    includes = f'  <xacro:include filename="$(find {package})/robots/{robot}/xacro/{robot}.description.xacro"/>'
+    if ros2_control is None:
         return f"""<?xml version="1.0"?>
 {_banner(robot)}
 <robot xmlns:xacro="http://www.ros.org/wiki/xacro" name="{robot}">
 
-  <xacro:include filename="$(find {package})/robots/{robot}/xacro/{robot}.description.xacro"/>
+{includes}
 
   <xacro:{robot}_description/>
 </robot>
 """
 
-    args = ros2_control.get("args", {})
-    arg_decls = "\n".join(f'  <xacro:arg name="{k}" default="{v}"/>' for k, v in args.items())
-    name_attr = ros2_control.get("combined_block_name", f"{robot}_system")
-    imu = ros2_control.get("imu")
-    imu_pass = '\n    imu_port="$(arg imu_port)"' if (imu and imu.get("real_plugin")) else ""
-    # Only pass use_linkage when a joint declares a four-bar, so robots without
-    # one regenerate byte-identically.
-    link_pass = ('\n    use_linkage="$(arg use_linkage)"'
-                 if any(j.get("linkage") for j in ros2_control.get("joints", [])) else "")
+    args = ros2_control["args"]
+    declarations = "\n".join(f'  <xacro:arg name="{k}" default="{v}"/>' for k, v in args.items())
+    forwarded = "\n".join(f'    {arg}="$(arg {arg})"' for arg in args)
     return f"""<?xml version="1.0"?>
 {_banner(robot)}
 <robot xmlns:xacro="http://www.ros.org/wiki/xacro" name="{robot}">
-{arg_decls}
+{declarations}
 
-  <xacro:include filename="$(find {package})/robots/{robot}/xacro/{robot}.description.xacro"/>
+{includes}
   <xacro:include filename="$(find {package})/robots/{robot}/xacro/{robot}.ros2_control.xacro"/>
 
   <xacro:{robot}_description/>
 
   <xacro:{robot}_ros2_control
-    name="{name_attr}"
-    use_fake_hardware="$(arg {MOCK_ARG})"
-    use_sim="$(arg {SIM_ARG})"
-    mode="$(arg mode)"
-    can_interface_left="$(arg can_interface_left)"
-    can_interface_right="$(arg can_interface_right)"
-    calibration_file="$(arg calibration_file)"{imu_pass}{link_pass}/>
+    name="{ros2_control["combined_block_name"]}"
+{forwarded}/>
 </robot>
 """
 
@@ -667,33 +381,33 @@ def build_assembly_xacro(robot: str, ros2_control: dict | None, package: str = D
 
 
 def generate(robot_dir: Path, package: str = DEFAULT_PACKAGE) -> list[Path]:
+    """Write the xacro artifacts for one ``robots/<robot>/`` directory."""
     robot = robot_dir.name
-    cad_dir = robot_dir / "cad"
-    # The committed, finalized flat URDF (base_link-free) is the kinematic hub.
     hub_urdf = robot_dir / "urdf" / f"{robot}.urdf"
-    joint_properties = json.loads((cad_dir / "joint_properties.json").read_text())
+    joint_properties = json.loads((robot_dir / "cad" / "joint_properties.json").read_text())
 
-    # ros2_control.json is optional: robots without it (e.g. the full lite)
-    # generate a model-only package -- description macro + a thin assembly, no
-    # <ros2_control>. Deployment wiring lives only where the hardware is known.
-    ros2_control_path = cad_dir / "ros2_control.json"
+    # ros2_control.json is optional. A robot without one (the full lite) generates a
+    # model-only package: a description macro and a thin assembly, no <ros2_control>.
+    # Deployment wiring lives only where the hardware is known.
+    ros2_control_path = robot_dir / "cad" / "ros2_control.json"
     ros2_control = json.loads(ros2_control_path.read_text()) if ros2_control_path.exists() else None
 
-    tree = robot_model.parse(hub_urdf)
-    root = tree.getroot()
-    limits = robot_model.joint_limits(root)
-    base_link = (ros2_control or {}).get("base_link") or {"name": "base_link", "child": robot_model.root_link(root)}
-
-    xacro_dir = robot_dir / "xacro"
-    xacro_dir.mkdir(parents=True, exist_ok=True)
+    root = robot_model.parse(hub_urdf).getroot()
+    base_link = (ros2_control or {}).get("base_link") or {
+        "name": "base_link", "child": robot_model.root_link(root),
+    }
 
     outputs = {
-        f"{robot}.description.xacro": build_description_xacro(hub_urdf, robot, joint_properties, base_link, package),
+        f"{robot}.description.xacro": build_description_xacro(
+            hub_urdf, robot, joint_properties, base_link, package),
         f"{robot}.urdf.xacro": build_assembly_xacro(robot, ros2_control, package),
     }
     if ros2_control is not None:
-        outputs[f"{robot}.ros2_control.xacro"] = build_ros2_control_xacro(robot, ros2_control, limits)
+        outputs[f"{robot}.ros2_control.xacro"] = build_ros2_control_xacro(
+            robot, ros2_control, robot_model.joint_limits(root))
 
+    xacro_dir = robot_dir / "xacro"
+    xacro_dir.mkdir(parents=True, exist_ok=True)
     written = []
     for filename, content in outputs.items():
         path = xacro_dir / filename
diff --git a/robots/lite/mjcf/lite.xml b/robots/lite/mjcf/lite.xml
index 291da4d..115cc9d 100644
--- a/robots/lite/mjcf/lite.xml
+++ b/robots/lite/mjcf/lite.xml
@@ -2,7 +2,6 @@
 <mujoco model="lite">
   <!-- GENERATED by robot_assets from Onshape CAD. Do not edit by hand. Regenerate: robot-assets-generate lite -->
   <compiler angle="radian" meshdir="../meshes/visual/" />
-
   <asset>
     <mesh name="pelvis_visual" content_type="model/stl" file="pelvis_visual.stl" />
     <mesh name="left_hip_pitch_visual" content_type="model/stl" file="left_hip_pitch_visual.stl" />
@@ -78,7 +77,6 @@
     <mesh name="neck_roll_visual" content_type="model/stl" file="neck_roll_visual.stl" />
     <mesh name="head_visual" content_type="model/stl" file="head_visual.stl" />
   </asset>
-
   <worldbody>
     <body name="pelvis">
       <inertial pos="0.0135183 5.78646e-07 0.0691358" quat="0.999848 -1.33806e-05 0.0174073 1.226e-05" mass="3.97182" diaginertia="0.0186941 0.015546 0.0121291" />
@@ -462,4 +460,78 @@
       </body>
     </body>
   </worldbody>
-<actuator><position name="left_hip_pitch" joint="left_hip_pitch" forcerange="-36.0 36.0" /><position name="left_hip_roll" joint="left_hip_roll" forcerange="-36.0 36.0" /><position name="left_hip_yaw" joint="left_hip_yaw" forcerange="-17.0 17.0" /><position name="left_knee_pitch" joint="left_knee_pitch" forcerange="-36.0 36.0" /><position name="left_ankle_yaw" joint="left_ankle_yaw" forcerange="-14.0 14.0" /><position name="left_ankle_pitch" joint="left_ankle_pitch" forcerange="-14.0 14.0" /><position name="left_ankle_roll" joint="left_ankle_roll" forcerange="-5.5 5.5" /><position name="right_hip_pitch" joint="right_hip_pitch" forcerange="-36.0 36.0" /><position name="right_hip_roll" joint="right_hip_roll" forcerange="-36.0 36.0" /><position name="right_hip_yaw" joint="right_hip_yaw" forcerange="-17.0 17.0" /><position name="right_knee_pitch" joint="right_knee_pitch" forcerange="-36.0 36.0" /><position name="right_ankle_yaw" joint="right_ankle_yaw" forcerange="-14.0 14.0" /><position name="right_ankle_pitch" joint="right_ankle_pitch" forcerange="-14.0 14.0" /><position name="right_ankle_roll" joint="right_ankle_roll" forcerange="-5.5 5.5" /><position name="waist_yaw" joint="waist_yaw" forcerange="-36.0 36.0" /><position name="left_shoulder_pitch" joint="left_shoulder_pitch" forcerange="-17.0 17.0" /><position name="left_shoulder_roll" joint="left_shoulder_roll" forcerange="-14.0 14.0" /><position name="left_shoulder_yaw" joint="left_shoulder_yaw" forcerange="-14.0 14.0" /><position name="left_elbow_pitch" joint="left_elbow_pitch" forcerange="-14.0 14.0" /><position name="left_wrist_yaw" joint="left_wrist_yaw" forcerange="-5.5 5.5" /><position name="left_wrist_roll" joint="left_wrist_roll" forcerange="-5.5 5.5" /><position name="left_wrist_pitch" joint="left_wrist_pitch" forcerange="-5.5 5.5" /><position name="left_finger1_j1" joint="left_finger1_j1" forcerange="-10 10" /><position name="left_finger1_j2" joint="left_finger1_j2" forcerange="-10 10" /><position name="left_finger1_j3" joint="left_finger1_j3" forcerange="-10 10" /><position name="left_finger1_j4" joint="left_finger1_j4" forcerange="-10 10" /><position name="left_finger2_j1" joint="left_finger2_j1" forcerange="-10 10" /><position name="left_finger2_j2" joint="left_finger2_j2" forcerange="-10 10" /><position name="left_finger2_j3" joint="left_finger2_j3" forcerange="-10 10" /><position name="left_finger2_j4" joint="left_finger2_j4" forcerange="-10 10" /><position name="left_finger3_j1" joint="left_finger3_j1" forcerange="-10 10" /><position name="left_finger3_j2" joint="left_finger3_j2" forcerange="-10 10" /><position name="left_finger3_j3" joint="left_finger3_j3" forcerange="-10 10" /><position name="left_finger3_j4" joint="left_finger3_j4" forcerange="-10 10" /><position name="left_finger4_j1" joint="left_finger4_j1" forcerange="-10 10" /><position name="left_finger4_j2" joint="left_finger4_j2" forcerange="-10 10" /><position name="left_finger4_j3" joint="left_finger4_j3" forcerange="-10 10" /><position name="left_finger4_j4" joint="left_finger4_j4" forcerange="-10 10" /><position name="left_finger5_j1" joint="left_finger5_j1" forcerange="-10 10" /><position name="left_finger5_j2" joint="left_finger5_j2" forcerange="-10 10" /><position name="left_finger5_j3" joint="left_finger5_j3" forcerange="-10 10" /><position name="left_finger5_j4" joint="left_finger5_j4" forcerange="-10 10" /><position name="right_shoulder_pitch" joint="right_shoulder_pitch" forcerange="-17.0 17.0" /><position name="right_shoulder_roll" joint="right_shoulder_roll" forcerange="-14.0 14.0" /><position name="right_shoulder_yaw" joint="right_shoulder_yaw" forcerange="-14.0 14.0" /><position name="right_elbow_pitch" joint="right_elbow_pitch" forcerange="-14.0 14.0" /><position name="right_wrist_yaw" joint="right_wrist_yaw" forcerange="-5.5 5.5" /><position name="right_wrist_roll" joint="right_wrist_roll" forcerange="-5.5 5.5" /><position name="right_wrist_pitch" joint="right_wrist_pitch" forcerange="-5.5 5.5" /><position name="right_finger1_j1" joint="right_finger1_j1" forcerange="-10 10" /><position name="right_finger1_j2" joint="right_finger1_j2" forcerange="-10 10" /><position name="right_finger1_j3" joint="right_finger1_j3" forcerange="-10 10" /><position name="right_finger1_j4" joint="right_finger1_j4" forcerange="-10 10" /><position name="right_finger2_j1" joint="right_finger2_j1" forcerange="-10 10" /><position name="right_finger2_j2" joint="right_finger2_j2" forcerange="-10 10" /><position name="right_finger2_j3" joint="right_finger2_j3" forcerange="-10 10" /><position name="right_finger2_j4" joint="right_finger2_j4" forcerange="-10 10" /><position name="right_finger3_j1" joint="right_finger3_j1" forcerange="-10 10" /><position name="right_finger3_j2" joint="right_finger3_j2" forcerange="-10 10" /><position name="right_finger3_j3" joint="right_finger3_j3" forcerange="-10 10" /><position name="right_finger3_j4" joint="right_finger3_j4" forcerange="-10 10" /><position name="right_finger4_j1" joint="right_finger4_j1" forcerange="-10 10" /><position name="right_finger4_j2" joint="right_finger4_j2" forcerange="-10 10" /><position name="right_finger4_j3" joint="right_finger4_j3" forcerange="-10 10" /><position name="right_finger4_j4" joint="right_finger4_j4" forcerange="-10 10" /><position name="right_finger5_j1" joint="right_finger5_j1" forcerange="-10 10" /><position name="right_finger5_j2" joint="right_finger5_j2" forcerange="-10 10" /><position name="right_finger5_j3" joint="right_finger5_j3" forcerange="-10 10" /><position name="right_finger5_j4" joint="right_finger5_j4" forcerange="-10 10" /><position name="neck_yaw" joint="neck_yaw" forcerange="-4.8 4.8" /><position name="neck_roll" joint="neck_roll" forcerange="-4.8 4.8" /><position name="neck_pitch" joint="neck_pitch" forcerange="-4.8 4.8" /></actuator></mujoco>
\ No newline at end of file
+  <actuator>
+    <position name="left_hip_pitch" joint="left_hip_pitch" forcerange="-36.0 36.0" />
+    <position name="left_hip_roll" joint="left_hip_roll" forcerange="-36.0 36.0" />
+    <position name="left_hip_yaw" joint="left_hip_yaw" forcerange="-17.0 17.0" />
+    <position name="left_knee_pitch" joint="left_knee_pitch" forcerange="-36.0 36.0" />
+    <position name="left_ankle_yaw" joint="left_ankle_yaw" forcerange="-14.0 14.0" />
+    <position name="left_ankle_pitch" joint="left_ankle_pitch" forcerange="-14.0 14.0" />
+    <position name="left_ankle_roll" joint="left_ankle_roll" forcerange="-5.5 5.5" />
+    <position name="right_hip_pitch" joint="right_hip_pitch" forcerange="-36.0 36.0" />
+    <position name="right_hip_roll" joint="right_hip_roll" forcerange="-36.0 36.0" />
+    <position name="right_hip_yaw" joint="right_hip_yaw" forcerange="-17.0 17.0" />
+    <position name="right_knee_pitch" joint="right_knee_pitch" forcerange="-36.0 36.0" />
+    <position name="right_ankle_yaw" joint="right_ankle_yaw" forcerange="-14.0 14.0" />
+    <position name="right_ankle_pitch" joint="right_ankle_pitch" forcerange="-14.0 14.0" />
+    <position name="right_ankle_roll" joint="right_ankle_roll" forcerange="-5.5 5.5" />
+    <position name="waist_yaw" joint="waist_yaw" forcerange="-36.0 36.0" />
+    <position name="left_shoulder_pitch" joint="left_shoulder_pitch" forcerange="-17.0 17.0" />
+    <position name="left_shoulder_roll" joint="left_shoulder_roll" forcerange="-14.0 14.0" />
+    <position name="left_shoulder_yaw" joint="left_shoulder_yaw" forcerange="-14.0 14.0" />
+    <position name="left_elbow_pitch" joint="left_elbow_pitch" forcerange="-14.0 14.0" />
+    <position name="left_wrist_yaw" joint="left_wrist_yaw" forcerange="-5.5 5.5" />
+    <position name="left_wrist_roll" joint="left_wrist_roll" forcerange="-5.5 5.5" />
+    <position name="left_wrist_pitch" joint="left_wrist_pitch" forcerange="-5.5 5.5" />
+    <position name="left_finger1_j1" joint="left_finger1_j1" forcerange="-10 10" />
+    <position name="left_finger1_j2" joint="left_finger1_j2" forcerange="-10 10" />
+    <position name="left_finger1_j3" joint="left_finger1_j3" forcerange="-10 10" />
+    <position name="left_finger1_j4" joint="left_finger1_j4" forcerange="-10 10" />
+    <position name="left_finger2_j1" joint="left_finger2_j1" forcerange="-10 10" />
+    <position name="left_finger2_j2" joint="left_finger2_j2" forcerange="-10 10" />
+    <position name="left_finger2_j3" joint="left_finger2_j3" forcerange="-10 10" />
+    <position name="left_finger2_j4" joint="left_finger2_j4" forcerange="-10 10" />
+    <position name="left_finger3_j1" joint="left_finger3_j1" forcerange="-10 10" />
+    <position name="left_finger3_j2" joint="left_finger3_j2" forcerange="-10 10" />
+    <position name="left_finger3_j3" joint="left_finger3_j3" forcerange="-10 10" />
+    <position name="left_finger3_j4" joint="left_finger3_j4" forcerange="-10 10" />
+    <position name="left_finger4_j1" joint="left_finger4_j1" forcerange="-10 10" />
+    <position name="left_finger4_j2" joint="left_finger4_j2" forcerange="-10 10" />
+    <position name="left_finger4_j3" joint="left_finger4_j3" forcerange="-10 10" />
+    <position name="left_finger4_j4" joint="left_finger4_j4" forcerange="-10 10" />
+    <position name="left_finger5_j1" joint="left_finger5_j1" forcerange="-10 10" />
+    <position name="left_finger5_j2" joint="left_finger5_j2" forcerange="-10 10" />
+    <position name="left_finger5_j3" joint="left_finger5_j3" forcerange="-10 10" />
+    <position name="left_finger5_j4" joint="left_finger5_j4" forcerange="-10 10" />
+    <position name="right_shoulder_pitch" joint="right_shoulder_pitch" forcerange="-17.0 17.0" />
+    <position name="right_shoulder_roll" joint="right_shoulder_roll" forcerange="-14.0 14.0" />
+    <position name="right_shoulder_yaw" joint="right_shoulder_yaw" forcerange="-14.0 14.0" />
+    <position name="right_elbow_pitch" joint="right_elbow_pitch" forcerange="-14.0 14.0" />
+    <position name="right_wrist_yaw" joint="right_wrist_yaw" forcerange="-5.5 5.5" />
+    <position name="right_wrist_roll" joint="right_wrist_roll" forcerange="-5.5 5.5" />
+    <position name="right_wrist_pitch" joint="right_wrist_pitch" forcerange="-5.5 5.5" />
+    <position name="right_finger1_j1" joint="right_finger1_j1" forcerange="-10 10" />
+    <position name="right_finger1_j2" joint="right_finger1_j2" forcerange="-10 10" />
+    <position name="right_finger1_j3" joint="right_finger1_j3" forcerange="-10 10" />
+    <position name="right_finger1_j4" joint="right_finger1_j4" forcerange="-10 10" />
+    <position name="right_finger2_j1" joint="right_finger2_j1" forcerange="-10 10" />
+    <position name="right_finger2_j2" joint="right_finger2_j2" forcerange="-10 10" />
+    <position name="right_finger2_j3" joint="right_finger2_j3" forcerange="-10 10" />
+    <position name="right_finger2_j4" joint="right_finger2_j4" forcerange="-10 10" />
+    <position name="right_finger3_j1" joint="right_finger3_j1" forcerange="-10 10" />
+    <position name="right_finger3_j2" joint="right_finger3_j2" forcerange="-10 10" />
+    <position name="right_finger3_j3" joint="right_finger3_j3" forcerange="-10 10" />
+    <position name="right_finger3_j4" joint="right_finger3_j4" forcerange="-10 10" />
+    <position name="right_finger4_j1" joint="right_finger4_j1" forcerange="-10 10" />
+    <position name="right_finger4_j2" joint="right_finger4_j2" forcerange="-10 10" />
+    <position name="right_finger4_j3" joint="right_finger4_j3" forcerange="-10 10" />
+    <position name="right_finger4_j4" joint="right_finger4_j4" forcerange="-10 10" />
+    <position name="right_finger5_j1" joint="right_finger5_j1" forcerange="-10 10" />
+    <position name="right_finger5_j2" joint="right_finger5_j2" forcerange="-10 10" />
+    <position name="right_finger5_j3" joint="right_finger5_j3" forcerange="-10 10" />
+    <position name="right_finger5_j4" joint="right_finger5_j4" forcerange="-10 10" />
+    <position name="neck_yaw" joint="neck_yaw" forcerange="-4.8 4.8" />
+    <position name="neck_roll" joint="neck_roll" forcerange="-4.8 4.8" />
+    <position name="neck_pitch" joint="neck_pitch" forcerange="-4.8 4.8" />
+  </actuator>
+</mujoco>
\ No newline at end of file
diff --git a/robots/lite_bimanual/cad/ros2_control.json b/robots/lite_bimanual/cad/ros2_control.json
index c6290eb..822f308 100644
--- a/robots/lite_bimanual/cad/ros2_control.json
+++ b/robots/lite_bimanual/cad/ros2_control.json
@@ -13,9 +13,8 @@
     },
 
     "args": {
-        "use_fake_hardware": "true",
-        "use_sim": "false",
-        "mode": "arms",
+        "use_mock_hardware": "true",
+        "sim_mujoco": "false",
         "can_interface_left": "can0",
         "can_interface_right": "can1",
         "calibration_file": ""
@@ -30,10 +29,6 @@
         {"name": "right_arm", "block_name": "LiteRightArm", "can_interface_arg": "can_interface_right"}
     ],
 
-    "modes": {
-        "arms": ["left_arm", "right_arm"]
-    },
-
     "joints": [
         {"name": "left_shoulder_pitch",  "group": "left_arm",  "can_id": 11, "model": "rs-02", "direction": -1, "torque_limit": 17,  "current_limit": 27},
         {"name": "left_shoulder_roll",   "group": "left_arm",  "can_id": 12, "model": "rs-00", "direction": -1, "torque_limit": 14,  "current_limit": 16},
diff --git a/robots/lite_bimanual/mjcf/lite_bimanual.xml b/robots/lite_bimanual/mjcf/lite_bimanual.xml
index 52a6ccd..4fcb03e 100644
--- a/robots/lite_bimanual/mjcf/lite_bimanual.xml
+++ b/robots/lite_bimanual/mjcf/lite_bimanual.xml
@@ -2,8 +2,8 @@
 <mujoco model="lite_bimanual">
   <!-- GENERATED by robot_assets from Onshape CAD. Do not edit by hand. Regenerate: robot-assets-generate lite_bimanual -->
   <compiler angle="radian" meshdir="../meshes/visual/" />
-
-  <option timestep="0.001" integrator="implicitfast" solver="Newton" cone="elliptic" impratio="10" /><asset>
+  <option timestep="0.001" integrator="implicitfast" solver="Newton" cone="elliptic" impratio="10" />
+  <asset>
     <mesh name="chest_visual" content_type="model/stl" file="chest_visual.stl" />
     <mesh name="left_shoulder_pitch_visual" content_type="model/stl" file="left_shoulder_pitch_visual.stl" />
     <mesh name="left_shoulder_roll_visual" content_type="model/stl" file="left_shoulder_roll_visual.stl" />
@@ -20,7 +20,6 @@
     <mesh name="right_wrist_roll_visual" content_type="model/stl" file="right_wrist_roll_visual.stl" />
     <mesh name="right_hand_visual" content_type="model/stl" file="right_hand_visual.stl" />
   </asset>
-
   <worldbody>
     <body name="chest">
       <inertial pos="0.0223994 -6.1147e-08 0.218844" quat="0.991874 4.90987e-06 0.127224 -6.29771e-07" mass="5.67528" diaginertia="0.120398 0.116403 0.0510428" />
@@ -114,4 +113,20 @@
       </body>
     </body>
   </worldbody>
-<actuator><position name="left_shoulder_pitch" joint="left_shoulder_pitch" forcerange="-17 17" /><position name="left_shoulder_roll" joint="left_shoulder_roll" forcerange="-14 14" /><position name="left_shoulder_yaw" joint="left_shoulder_yaw" forcerange="-14 14" /><position name="left_elbow_pitch" joint="left_elbow_pitch" forcerange="-14 14" /><position name="left_wrist_yaw" joint="left_wrist_yaw" forcerange="-5.5 5.5" /><position name="left_wrist_roll" joint="left_wrist_roll" forcerange="-5.5 5.5" /><position name="left_wrist_pitch" joint="left_wrist_pitch" forcerange="-5.5 5.5" /><position name="right_shoulder_pitch" joint="right_shoulder_pitch" forcerange="-17 17" /><position name="right_shoulder_roll" joint="right_shoulder_roll" forcerange="-14 14" /><position name="right_shoulder_yaw" joint="right_shoulder_yaw" forcerange="-14 14" /><position name="right_elbow_pitch" joint="right_elbow_pitch" forcerange="-14 14" /><position name="right_wrist_yaw" joint="right_wrist_yaw" forcerange="-5.5 5.5" /><position name="right_wrist_roll" joint="right_wrist_roll" forcerange="-5.5 5.5" /><position name="right_wrist_pitch" joint="right_wrist_pitch" forcerange="-5.5 5.5" /></actuator></mujoco>
\ No newline at end of file
+  <actuator>
+    <position name="left_shoulder_pitch" joint="left_shoulder_pitch" forcerange="-17 17" />
+    <position name="left_shoulder_roll" joint="left_shoulder_roll" forcerange="-14 14" />
+    <position name="left_shoulder_yaw" joint="left_shoulder_yaw" forcerange="-14 14" />
+    <position name="left_elbow_pitch" joint="left_elbow_pitch" forcerange="-14 14" />
+    <position name="left_wrist_yaw" joint="left_wrist_yaw" forcerange="-5.5 5.5" />
+    <position name="left_wrist_roll" joint="left_wrist_roll" forcerange="-5.5 5.5" />
+    <position name="left_wrist_pitch" joint="left_wrist_pitch" forcerange="-5.5 5.5" />
+    <position name="right_shoulder_pitch" joint="right_shoulder_pitch" forcerange="-17 17" />
+    <position name="right_shoulder_roll" joint="right_shoulder_roll" forcerange="-14 14" />
+    <position name="right_shoulder_yaw" joint="right_shoulder_yaw" forcerange="-14 14" />
+    <position name="right_elbow_pitch" joint="right_elbow_pitch" forcerange="-14 14" />
+    <position name="right_wrist_yaw" joint="right_wrist_yaw" forcerange="-5.5 5.5" />
+    <position name="right_wrist_roll" joint="right_wrist_roll" forcerange="-5.5 5.5" />
+    <position name="right_wrist_pitch" joint="right_wrist_pitch" forcerange="-5.5 5.5" />
+  </actuator>
+</mujoco>
\ No newline at end of file
diff --git a/robots/lite_bimanual/xacro/lite_bimanual.ros2_control.xacro b/robots/lite_bimanual/xacro/lite_bimanual.ros2_control.xacro
index 23bf343..b78dda9 100644
--- a/robots/lite_bimanual/xacro/lite_bimanual.ros2_control.xacro
+++ b/robots/lite_bimanual/xacro/lite_bimanual.ros2_control.xacro
@@ -3,11 +3,11 @@
 <robot xmlns:xacro="http://www.ros.org/wiki/xacro">
 
   <!-- One joint: 5 command + 3 state interfaces (MIT mode).
-       Real-only hardware params are emitted under xacro:unless (sim/mock ignore them). -->
+       The params are read by humanoid_devices_robstride. The mock and MuJoCo backends
+       ignore params they do not know, so this one macro serves all three. -->
   <xacro:macro name="lite_bimanual_joint"
-               params="name can_id model direction
-                       lower_limit upper_limit torque_limit current_limit
-                       use_fake_hardware use_sim">
+               params="name can_id model direction lower_limit upper_limit torque_limit
+                       current_limit">
     <joint name="${name}">
       <command_interface name="position"/>
       <command_interface name="velocity"/>
@@ -17,107 +17,91 @@
       <state_interface name="position"/>
       <state_interface name="velocity"/>
       <state_interface name="effort"/>
-      <xacro:unless value="${use_sim or use_fake_hardware}">
-        <param name="can_id">${can_id}</param>
-        <param name="model">${model}</param>
-        <param name="direction">${direction}</param>
-        <param name="lower_limit">${lower_limit}</param>
-        <param name="upper_limit">${upper_limit}</param>
-        <param name="torque_limit">${torque_limit}</param>
-        <param name="current_limit">${current_limit}</param>
-      </xacro:unless>
+      <param name="can_id">${can_id}</param>
+      <param name="model">${model}</param>
+      <param name="direction">${direction}</param>
+      <param name="lower_limit">${lower_limit}</param>
+      <param name="upper_limit">${upper_limit}</param>
+      <param name="torque_limit">${torque_limit}</param>
+      <param name="current_limit">${current_limit}</param>
     </joint>
   </xacro:macro>
 
-  <xacro:macro name="lite_bimanual_left_arm_joints" params="use_fake_hardware use_sim">
+  <xacro:macro name="lite_bimanual_left_arm_joints">
     <xacro:lite_bimanual_joint name="left_shoulder_pitch" can_id="11" model="rs-02" direction="-1"
-                      lower_limit="-3.14159" upper_limit="0.785398"
-                      torque_limit="17" current_limit="27"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                               lower_limit="-3.14159" upper_limit="0.785398" torque_limit="17"
+                               current_limit="27"/>
     <xacro:lite_bimanual_joint name="left_shoulder_roll" can_id="12" model="rs-00" direction="-1"
-                      lower_limit="-1.5708" upper_limit="1.91986"
-                      torque_limit="14" current_limit="16"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                               lower_limit="-1.5708" upper_limit="1.91986" torque_limit="14"
+                               current_limit="16"/>
     <xacro:lite_bimanual_joint name="left_shoulder_yaw" can_id="13" model="rs-00" direction="1"
-                      lower_limit="-1.5708" upper_limit="1.5708"
-                      torque_limit="14" current_limit="16"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                               lower_limit="-1.5708" upper_limit="1.5708" torque_limit="14"
+                               current_limit="16"/>
     <xacro:lite_bimanual_joint name="left_elbow_pitch" can_id="14" model="rs-00" direction="-1"
-                      lower_limit="-2.35619" upper_limit="0.0"
-                      torque_limit="14" current_limit="16"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                               lower_limit="-2.35619" upper_limit="0.0" torque_limit="14"
+                               current_limit="16"/>
     <xacro:lite_bimanual_joint name="left_wrist_yaw" can_id="15" model="rs-05" direction="1"
-                      lower_limit="-2.0944" upper_limit="1.5708"
-                      torque_limit="4.0" current_limit="14"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                               lower_limit="-2.0944" upper_limit="1.5708" torque_limit="4.0"
+                               current_limit="14"/>
     <xacro:lite_bimanual_joint name="left_wrist_roll" can_id="16" model="rs-05" direction="-1"
-                      lower_limit="-0.698132" upper_limit="0.698132"
-                      torque_limit="4.0" current_limit="14"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                               lower_limit="-0.698132" upper_limit="0.698132" torque_limit="4.0"
+                               current_limit="14"/>
     <xacro:lite_bimanual_joint name="left_wrist_pitch" can_id="17" model="rs-05" direction="-1"
-                      lower_limit="-0.785398" upper_limit="0.785398"
-                      torque_limit="4.0" current_limit="14"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                               lower_limit="-0.785398" upper_limit="0.785398" torque_limit="4.0"
+                               current_limit="14"/>
   </xacro:macro>
 
-  <xacro:macro name="lite_bimanual_right_arm_joints" params="use_fake_hardware use_sim">
+  <xacro:macro name="lite_bimanual_right_arm_joints">
     <xacro:lite_bimanual_joint name="right_shoulder_pitch" can_id="21" model="rs-02" direction="1"
-                      lower_limit="-3.14159" upper_limit="0.785398"
-                      torque_limit="17" current_limit="27"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                               lower_limit="-3.14159" upper_limit="0.785398" torque_limit="17"
+                               current_limit="27"/>
     <xacro:lite_bimanual_joint name="right_shoulder_roll" can_id="22" model="rs-00" direction="-1"
-                      lower_limit="-1.91986" upper_limit="1.5708"
-                      torque_limit="14" current_limit="16"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                               lower_limit="-1.91986" upper_limit="1.5708" torque_limit="14"
+                               current_limit="16"/>
     <xacro:lite_bimanual_joint name="right_shoulder_yaw" can_id="23" model="rs-00" direction="1"
-                      lower_limit="-1.5708" upper_limit="1.5708"
-                      torque_limit="14" current_limit="16"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                               lower_limit="-1.5708" upper_limit="1.5708" torque_limit="14"
+                               current_limit="16"/>
     <xacro:lite_bimanual_joint name="right_elbow_pitch" can_id="24" model="rs-00" direction="1"
-                      lower_limit="-2.35619" upper_limit="0.0"
-                      torque_limit="14" current_limit="16"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                               lower_limit="-2.35619" upper_limit="0.0" torque_limit="14"
+                               current_limit="16"/>
     <xacro:lite_bimanual_joint name="right_wrist_yaw" can_id="25" model="rs-05" direction="1"
-                      lower_limit="-1.5708" upper_limit="2.0944"
-                      torque_limit="4.0" current_limit="14"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                               lower_limit="-1.5708" upper_limit="2.0944" torque_limit="4.0"
+                               current_limit="14"/>
     <xacro:lite_bimanual_joint name="right_wrist_roll" can_id="26" model="rs-05" direction="1"
-                      lower_limit="-0.698132" upper_limit="0.698132"
-                      torque_limit="4.0" current_limit="14"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                               lower_limit="-0.698132" upper_limit="0.698132" torque_limit="4.0"
+                               current_limit="14"/>
     <xacro:lite_bimanual_joint name="right_wrist_pitch" can_id="27" model="rs-05" direction="-1"
-                      lower_limit="-0.785398" upper_limit="0.785398"
-                      torque_limit="4.0" current_limit="14"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                               lower_limit="-0.785398" upper_limit="0.785398" torque_limit="4.0"
+                               current_limit="14"/>
   </xacro:macro>
 
-  <!-- Combined single-block layout for the sim and mock backends. -->
-  <xacro:macro name="lite_bimanual_ros2_control_combined" params="name use_fake_hardware use_sim">
+  <!-- Combined single block for the mock and MuJoCo backends. -->
+  <xacro:macro name="lite_bimanual_ros2_control_combined" params="name sim_mujoco">
     <ros2_control name="${name}" type="system">
       <hardware>
-        <xacro:if value="${use_sim}">
+        <xacro:if value="${sim_mujoco}">
           <plugin>mujoco_ros2_control/MujocoSystem</plugin>
         </xacro:if>
-        <xacro:unless value="${use_sim}">
+        <xacro:unless value="${sim_mujoco}">
           <plugin>mock_components/GenericSystem</plugin>
         </xacro:unless>
       </hardware>
-      <xacro:lite_bimanual_left_arm_joints use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
-      <xacro:lite_bimanual_right_arm_joints use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+      <xacro:lite_bimanual_left_arm_joints/>
+      <xacro:lite_bimanual_right_arm_joints/>
     </ros2_control>
   </xacro:macro>
 
   <!-- Real hardware: one <ros2_control> block per CAN bus. The controller_manager
        runs them concurrently and exposes a single flat joint list to controllers. -->
   <xacro:macro name="lite_bimanual_ros2_control_real"
-               params="mode can_interface_left can_interface_right calibration_file">
+               params="can_interface_left can_interface_right calibration_file">
     <ros2_control name="LiteLeftArm" type="system">
       <hardware>
         <plugin>humanoid_devices_robstride/RobstrideSystem</plugin>
         <param name="can_interface">${can_interface_left}</param>
         <param name="calibration_file">${calibration_file}</param>
       </hardware>
-      <xacro:lite_bimanual_left_arm_joints use_fake_hardware="false" use_sim="false"/>
+      <xacro:lite_bimanual_left_arm_joints/>
     </ros2_control>
     <ros2_control name="LiteRightArm" type="system">
       <hardware>
@@ -125,21 +109,21 @@
         <param name="can_interface">${can_interface_right}</param>
         <param name="calibration_file">${calibration_file}</param>
       </hardware>
-      <xacro:lite_bimanual_right_arm_joints use_fake_hardware="false" use_sim="false"/>
+      <xacro:lite_bimanual_right_arm_joints/>
     </ros2_control>
   </xacro:macro>
 
-  <!-- Top-level dispatch: combined block for sim/mock, per-bus blocks for real
-       (use_sim wins over use_fake_hardware, matching franka_ros2 / UR precedence). -->
+  <!-- Backend dispatch, following the Universal Robots description convention: one
+       boolean per non-real backend, real hardware as the fallback when both are false.
+       sim_mujoco wins over use_mock_hardware. -->
   <xacro:macro name="lite_bimanual_ros2_control"
-               params="name use_fake_hardware use_sim mode
-                       can_interface_left can_interface_right calibration_file">
-    <xacro:if value="${use_sim or use_fake_hardware}">
-      <xacro:lite_bimanual_ros2_control_combined name="${name}"
-        use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+               params="name use_mock_hardware sim_mujoco can_interface_left can_interface_right
+                       calibration_file">
+    <xacro:if value="${sim_mujoco or use_mock_hardware}">
+      <xacro:lite_bimanual_ros2_control_combined name="${name}" sim_mujoco="${sim_mujoco}"/>
     </xacro:if>
-    <xacro:unless value="${use_sim or use_fake_hardware}">
-      <xacro:lite_bimanual_ros2_control_real mode="${mode}"
+    <xacro:unless value="${sim_mujoco or use_mock_hardware}">
+      <xacro:lite_bimanual_ros2_control_real
         can_interface_left="${can_interface_left}"
         can_interface_right="${can_interface_right}"
         calibration_file="${calibration_file}"/>
diff --git a/robots/lite_bimanual/xacro/lite_bimanual.urdf.xacro b/robots/lite_bimanual/xacro/lite_bimanual.urdf.xacro
index ae6cf8c..7ed20e1 100644
--- a/robots/lite_bimanual/xacro/lite_bimanual.urdf.xacro
+++ b/robots/lite_bimanual/xacro/lite_bimanual.urdf.xacro
@@ -1,9 +1,8 @@
 <?xml version="1.0"?>
 <!-- GENERATED by robot_assets from Onshape CAD. Do not edit by hand. Regenerate: robot-assets-generate lite_bimanual -->
 <robot xmlns:xacro="http://www.ros.org/wiki/xacro" name="lite_bimanual">
-  <xacro:arg name="use_fake_hardware" default="true"/>
-  <xacro:arg name="use_sim" default="false"/>
-  <xacro:arg name="mode" default="arms"/>
+  <xacro:arg name="use_mock_hardware" default="true"/>
+  <xacro:arg name="sim_mujoco" default="false"/>
   <xacro:arg name="can_interface_left" default="can0"/>
   <xacro:arg name="can_interface_right" default="can1"/>
   <xacro:arg name="calibration_file" default=""/>
@@ -15,9 +14,8 @@
 
   <xacro:lite_bimanual_ros2_control
     name="LiteHardware"
-    use_fake_hardware="$(arg use_fake_hardware)"
-    use_sim="$(arg use_sim)"
-    mode="$(arg mode)"
+    use_mock_hardware="$(arg use_mock_hardware)"
+    sim_mujoco="$(arg sim_mujoco)"
     can_interface_left="$(arg can_interface_left)"
     can_interface_right="$(arg can_interface_right)"
     calibration_file="$(arg calibration_file)"/>
diff --git a/robots/lite_biped/cad/ros2_control.json b/robots/lite_biped/cad/ros2_control.json
index 1ca5f59..8c676df 100644
--- a/robots/lite_biped/cad/ros2_control.json
+++ b/robots/lite_biped/cad/ros2_control.json
@@ -1,5 +1,5 @@
 {
-    "_comment": "ROS 2 hardware mapping for the lite_biped (legs-only floating-base humanoid). Drives generation of xacro/lite_biped.ros2_control.xacro. Joint position limits come from the URDF (single source). The sim/mock combined block also advertises a base IMU <sensor> (use_sim only), backed by the MJCF base_quat/base_gyro/base_accel sensors via MujocoSystem and republished by imu_sensor_broadcaster. real-hardware can_id set from a live bus scan (left can2 ids 31-37, right can3 ids 41-47); direction/current_limit still pending commissioning + leg calibration. ankle_pitch carries a FOUR-BAR linkage (actuator in the shin pushes a coupler to a crank on the foot): ground = sqrt(160^2+12^2) = 160.449369 mm (the actuator pivot is 160 above / 12 BEHIND the ankle pivot, so the ground link is NOT 160), cranks 40, coupler 150, alpha_zero 338.822130 deg, sign +1 -- verified against CAD (the coupler closes to 150.0000 mm at joint -30/0/+50). RobstrideSystem converts joint<->actuator through it and refers the commanded impedance by J^2. Pass use_linkage:=false for calibration, which needs raw actuator angles.",
+    "_comment": "ROS 2 hardware mapping for the lite_biped (legs-only floating-base humanoid). Drives generation of xacro/lite_biped.ros2_control.xacro. Joint position limits come from the URDF (single source). The sim/mock combined block also advertises a base IMU <sensor> (sim_mujoco only), backed by the MJCF base_quat/base_gyro/base_accel sensors via MujocoSystem and republished by imu_sensor_broadcaster. real-hardware can_id set from a live bus scan (left can2 ids 31-37, right can3 ids 41-47); direction/current_limit still pending commissioning + leg calibration. ankle_pitch carries a FOUR-BAR linkage (actuator in the shin pushes a coupler to a crank on the foot): ground = sqrt(160^2+12^2) = 160.449369 mm (the actuator pivot is 160 above / 12 BEHIND the ankle pivot, so the ground link is NOT 160), cranks 40, coupler 150, alpha_zero 338.822130 deg, sign +1 -- verified against CAD (the coupler closes to 150.0000 mm at joint -30/0/+50). RobstrideSystem converts joint<->actuator through it and refers the commanded impedance by J^2. Pass use_linkage:=false for calibration, which needs raw actuator angles.",
 
     "interfaces": {
         "command": ["position", "velocity", "effort", "stiffness", "damping"],
@@ -13,9 +13,8 @@
     },
 
     "args": {
-        "use_fake_hardware": "true",
-        "use_sim": "false",
-        "mode": "legs",
+        "use_mock_hardware": "true",
+        "sim_mujoco": "false",
         "can_interface_left": "can2",
         "can_interface_right": "can3",
         "calibration_file": "",
@@ -28,17 +27,13 @@
     "combined_block_name": "LiteBipedHardware",
 
     "_comment_imu": "Sim/mock: the base_imu <sensor> lives in the combined block, backed by MujocoSystem's MJCF sensors. Real: a standalone <ros2_control type='sensor'> block (real_block_name) driven by real_plugin (Yahboom WIT USB IMU on imu_port), exposing the SAME interfaces so imu_sensor_broadcaster republishes /imu/data identically -- no separate driver node.",
-    "imu": {"name": "base_imu", "real_plugin": "humanoid_devices_imu_hardware/YahboomImuSensor", "real_block_name": "LiteBipedIMU"},
+    "imu": {"name": "base_imu", "real_plugin": "humanoid_devices_witmotion/WitImuSensor", "real_block_name": "LiteBipedIMU"},
 
     "groups": [
         {"name": "left_leg",  "block_name": "LiteBipedLeftLeg",  "can_interface_arg": "can_interface_left"},
         {"name": "right_leg", "block_name": "LiteBipedRightLeg", "can_interface_arg": "can_interface_right"}
     ],
 
-    "modes": {
-        "legs": ["left_leg", "right_leg"]
-    },
-
     "joints": [
         {"name": "left_hip_pitch",   "group": "left_leg",  "can_id": 31, "model": "rs-06", "direction": -1, "torque_limit": 36.0, "current_limit": 43},
         {"name": "left_hip_roll",    "group": "left_leg",  "can_id": 32, "model": "rs-06", "direction": 1, "torque_limit": 36.0, "current_limit": 43},
diff --git a/robots/lite_biped/mjcf/lite_biped.xml b/robots/lite_biped/mjcf/lite_biped.xml
index 0d145ba..8fa0909 100644
--- a/robots/lite_biped/mjcf/lite_biped.xml
+++ b/robots/lite_biped/mjcf/lite_biped.xml
@@ -2,8 +2,8 @@
 <mujoco model="lite_biped">
   <!-- GENERATED by robot_assets from Onshape CAD. Do not edit by hand. Regenerate: robot-assets-generate lite_biped -->
   <compiler angle="radian" meshdir="../meshes/visual/" />
-
-  <option timestep="0.005" integrator="implicitfast" solver="Newton" cone="pyramidal" impratio="1" iterations="10" ls_iterations="20" /><asset>
+  <option timestep="0.005" integrator="implicitfast" solver="Newton" cone="pyramidal" impratio="1" iterations="10" ls_iterations="20" />
+  <asset>
     <mesh name="pelvis_visual" content_type="model/stl" file="pelvis_visual.stl" />
     <mesh name="left_hip_pitch_visual" content_type="model/stl" file="left_hip_pitch_visual.stl" />
     <mesh name="left_hip_roll_visual" content_type="model/stl" file="left_hip_roll_visual.stl" />
@@ -20,7 +20,6 @@
     <mesh name="right_ankle_pitch_visual" content_type="model/stl" file="right_ankle_pitch_visual.stl" />
     <mesh name="right_foot_visual" content_type="model/stl" file="right_foot_visual.stl" />
   </asset>
-
   <worldbody>
     <body name="pelvis">
       <joint name="floating_base_joint" type="free" limited="false" actuatorfrclimited="false" /><site name="imu_site" pos="0.0 0.0 0.08" /><inertial pos="0.0137049 6.97587e-07 0.0692011" quat="0.999864 -1.34288e-05 0.0164944 1.28012e-05" mass="2.1" diaginertia="0.00988318 0.00823366 0.0063777" />
@@ -126,4 +125,27 @@
       </body>
     </body>
   </worldbody>
-<sensor><framequat name="base_quat" objtype="site" objname="imu_site" /><gyro name="base_gyro" site="imu_site" /><accelerometer name="base_accel" site="imu_site" /><velocimeter name="base_vel" site="imu_site" /><framepos name="base_pos" objtype="site" objname="imu_site" /></sensor><actuator><position name="left_hip_pitch" joint="left_hip_pitch" forcerange="-36.0 36.0" /><position name="left_hip_roll" joint="left_hip_roll" forcerange="-36.0 36.0" /><position name="left_hip_yaw" joint="left_hip_yaw" forcerange="-17.0 17.0" /><position name="left_knee_pitch" joint="left_knee_pitch" forcerange="-36.0 36.0" /><position name="left_ankle_yaw" joint="left_ankle_yaw" forcerange="-14.0 14.0" /><position name="left_ankle_pitch" joint="left_ankle_pitch" forcerange="-14.0 14.0" /><position name="left_ankle_roll" joint="left_ankle_roll" forcerange="-5.5 5.5" /><position name="right_hip_pitch" joint="right_hip_pitch" forcerange="-36.0 36.0" /><position name="right_hip_roll" joint="right_hip_roll" forcerange="-36.0 36.0" /><position name="right_hip_yaw" joint="right_hip_yaw" forcerange="-17.0 17.0" /><position name="right_knee_pitch" joint="right_knee_pitch" forcerange="-36.0 36.0" /><position name="right_ankle_yaw" joint="right_ankle_yaw" forcerange="-14.0 14.0" /><position name="right_ankle_pitch" joint="right_ankle_pitch" forcerange="-14.0 14.0" /><position name="right_ankle_roll" joint="right_ankle_roll" forcerange="-5.5 5.5" /></actuator></mujoco>
\ No newline at end of file
+  <sensor>
+    <framequat name="base_quat" objtype="site" objname="imu_site" />
+    <gyro name="base_gyro" site="imu_site" />
+    <accelerometer name="base_accel" site="imu_site" />
+    <velocimeter name="base_vel" site="imu_site" />
+    <framepos name="base_pos" objtype="site" objname="imu_site" />
+  </sensor>
+  <actuator>
+    <position name="left_hip_pitch" joint="left_hip_pitch" forcerange="-36.0 36.0" />
+    <position name="left_hip_roll" joint="left_hip_roll" forcerange="-36.0 36.0" />
+    <position name="left_hip_yaw" joint="left_hip_yaw" forcerange="-17.0 17.0" />
+    <position name="left_knee_pitch" joint="left_knee_pitch" forcerange="-36.0 36.0" />
+    <position name="left_ankle_yaw" joint="left_ankle_yaw" forcerange="-14.0 14.0" />
+    <position name="left_ankle_pitch" joint="left_ankle_pitch" forcerange="-14.0 14.0" />
+    <position name="left_ankle_roll" joint="left_ankle_roll" forcerange="-5.5 5.5" />
+    <position name="right_hip_pitch" joint="right_hip_pitch" forcerange="-36.0 36.0" />
+    <position name="right_hip_roll" joint="right_hip_roll" forcerange="-36.0 36.0" />
+    <position name="right_hip_yaw" joint="right_hip_yaw" forcerange="-17.0 17.0" />
+    <position name="right_knee_pitch" joint="right_knee_pitch" forcerange="-36.0 36.0" />
+    <position name="right_ankle_yaw" joint="right_ankle_yaw" forcerange="-14.0 14.0" />
+    <position name="right_ankle_pitch" joint="right_ankle_pitch" forcerange="-14.0 14.0" />
+    <position name="right_ankle_roll" joint="right_ankle_roll" forcerange="-5.5 5.5" />
+  </actuator>
+</mujoco>
\ No newline at end of file
diff --git a/robots/lite_biped/xacro/lite_biped.ros2_control.xacro b/robots/lite_biped/xacro/lite_biped.ros2_control.xacro
index b21bb56..f2c603e 100644
--- a/robots/lite_biped/xacro/lite_biped.ros2_control.xacro
+++ b/robots/lite_biped/xacro/lite_biped.ros2_control.xacro
@@ -3,14 +3,11 @@
 <robot xmlns:xacro="http://www.ros.org/wiki/xacro">
 
   <!-- One joint: 5 command + 3 state interfaces (MIT mode).
-       Real-only hardware params are emitted under xacro:unless (sim/mock ignore them). -->
+       The params are read by humanoid_devices_robstride. The mock and MuJoCo backends
+       ignore params they do not know, so this one macro serves all three. -->
   <xacro:macro name="lite_biped_joint"
-               params="name can_id model direction
-                       lower_limit upper_limit torque_limit current_limit
-                       use_fake_hardware use_sim
-                       use_linkage:=true linkage_ground:=0
-                       linkage_crank_in:=0 linkage_coupler:=0 linkage_crank_out:=0
-                       linkage_alpha_zero:=0 linkage_sign:=1">
+               params="name can_id model direction lower_limit upper_limit torque_limit
+                       current_limit">
     <joint name="${name}">
       <command_interface name="position"/>
       <command_interface name="velocity"/>
@@ -20,121 +17,124 @@
       <state_interface name="position"/>
       <state_interface name="velocity"/>
       <state_interface name="effort"/>
-      <xacro:unless value="${use_sim or use_fake_hardware}">
-        <param name="can_id">${can_id}</param>
-        <param name="model">${model}</param>
-        <param name="direction">${direction}</param>
-        <param name="lower_limit">${lower_limit}</param>
-        <param name="upper_limit">${upper_limit}</param>
-        <param name="torque_limit">${torque_limit}</param>
-        <param name="current_limit">${current_limit}</param>
-        <!-- Four-bar transmission geometry, for joints that declare one in
-             ros2_control.json. The geometry is a PHYSICAL FACT so it is always
-             published: calibrate_robot reads it from /robot_description to refer
-             the URDF joint limits into actuator space, even on the runs where the
-             hardware plugin must NOT apply the transform. `linkage_enabled`
-             (= the use_linkage arg) is what switches the plugin's behaviour:
-             false during calibration, which needs raw actuator angles. With it
-             true, RobstrideSystem converts joint<->actuator through the linkage
-             and refers the commanded impedance by J^2, so /joint_states and every
-             controller speak true joint space. -->
-        <xacro:if value="${linkage_ground > 0}">
-          <param name="linkage_ground">${linkage_ground}</param>
-          <param name="linkage_crank_in">${linkage_crank_in}</param>
-          <param name="linkage_coupler">${linkage_coupler}</param>
-          <param name="linkage_crank_out">${linkage_crank_out}</param>
-          <param name="linkage_alpha_zero">${linkage_alpha_zero}</param>
-          <param name="linkage_sign">${linkage_sign}</param>
-          <param name="linkage_enabled">${use_linkage}</param>
-        </xacro:if>
-      </xacro:unless>
+      <param name="can_id">${can_id}</param>
+      <param name="model">${model}</param>
+      <param name="direction">${direction}</param>
+      <param name="lower_limit">${lower_limit}</param>
+      <param name="upper_limit">${upper_limit}</param>
+      <param name="torque_limit">${torque_limit}</param>
+      <param name="current_limit">${current_limit}</param>
+    </joint>
+  </xacro:macro>
+
+  <!-- A joint driven through a four-bar linkage, otherwise identical to
+       lite_biped_joint. The geometry is a physical fact, so it is always published:
+       calibrate_robot reads it from /robot_description to refer the URDF joint limits into
+       actuator space even on the runs where the plugin must not apply the transform.
+       linkage_enabled is the switch for that. With it true, RobstrideSystem converts
+       joint<->actuator through the linkage and refers the commanded impedance by J^2, so
+       /joint_states and every controller speak true joint space. Calibration sets it
+       false, because it needs raw actuator angles. -->
+  <xacro:macro name="lite_biped_linkage_joint"
+               params="name can_id model direction lower_limit upper_limit torque_limit
+                       current_limit linkage_ground linkage_crank_in linkage_coupler
+                       linkage_crank_out linkage_alpha_zero linkage_sign use_linkage">
+    <joint name="${name}">
+      <command_interface name="position"/>
+      <command_interface name="velocity"/>
+      <command_interface name="effort"/>
+      <command_interface name="stiffness"/>
+      <command_interface name="damping"/>
+      <state_interface name="position"/>
+      <state_interface name="velocity"/>
+      <state_interface name="effort"/>
+      <param name="can_id">${can_id}</param>
+      <param name="model">${model}</param>
+      <param name="direction">${direction}</param>
+      <param name="lower_limit">${lower_limit}</param>
+      <param name="upper_limit">${upper_limit}</param>
+      <param name="torque_limit">${torque_limit}</param>
+      <param name="current_limit">${current_limit}</param>
+      <param name="linkage_ground">${linkage_ground}</param>
+      <param name="linkage_crank_in">${linkage_crank_in}</param>
+      <param name="linkage_coupler">${linkage_coupler}</param>
+      <param name="linkage_crank_out">${linkage_crank_out}</param>
+      <param name="linkage_alpha_zero">${linkage_alpha_zero}</param>
+      <param name="linkage_sign">${linkage_sign}</param>
+      <param name="linkage_enabled">${use_linkage}</param>
     </joint>
   </xacro:macro>
 
-  <xacro:macro name="lite_biped_left_leg_joints" params="use_fake_hardware use_sim use_linkage:=true">
+  <xacro:macro name="lite_biped_left_leg_joints" params="use_linkage:=true">
     <xacro:lite_biped_joint name="left_hip_pitch" can_id="31" model="rs-06" direction="-1"
-                      lower_limit="-2.35619" upper_limit="0.785398"
-                      torque_limit="36.0" current_limit="43"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="-2.35619" upper_limit="0.785398" torque_limit="36.0"
+                            current_limit="43"/>
     <xacro:lite_biped_joint name="left_hip_roll" can_id="32" model="rs-06" direction="1"
-                      lower_limit="-0.349066" upper_limit="1.5708"
-                      torque_limit="36.0" current_limit="43"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="-0.349066" upper_limit="1.5708" torque_limit="36.0"
+                            current_limit="43"/>
     <xacro:lite_biped_joint name="left_hip_yaw" can_id="33" model="rs-02" direction="1"
-                      lower_limit="-1.5708" upper_limit="1.5708"
-                      torque_limit="17.0" current_limit="27"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="-1.5708" upper_limit="1.5708" torque_limit="17.0"
+                            current_limit="27"/>
     <xacro:lite_biped_joint name="left_knee_pitch" can_id="34" model="rs-06" direction="-1"
-                      lower_limit="0.0" upper_limit="2.35619"
-                      torque_limit="36.0" current_limit="43"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="0.0" upper_limit="2.35619" torque_limit="36.0"
+                            current_limit="43"/>
     <xacro:lite_biped_joint name="left_ankle_yaw" can_id="35" model="rs-00" direction="1"
-                      lower_limit="-1.5708" upper_limit="1.5708"
-                      torque_limit="14.0" current_limit="16"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
-    <xacro:lite_biped_joint name="left_ankle_pitch" can_id="36" model="rs-00" direction="1"
-                      lower_limit="-0.523599" upper_limit="0.872665"
-                      torque_limit="14.0" current_limit="16"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"
-                      linkage_ground="160.449369" linkage_crank_in="40.0"
-                      linkage_coupler="150.0" linkage_crank_out="40.0"
-                      linkage_alpha_zero="338.82213" linkage_sign="1"
-                      use_linkage="${use_linkage}"/>
+                            lower_limit="-1.5708" upper_limit="1.5708" torque_limit="14.0"
+                            current_limit="16"/>
+    <xacro:lite_biped_linkage_joint name="left_ankle_pitch" can_id="36" model="rs-00"
+                                    direction="1" lower_limit="-0.523599" upper_limit="0.872665"
+                                    torque_limit="14.0" current_limit="16"
+                                    linkage_ground="160.449369" linkage_crank_in="40.0"
+                                    linkage_coupler="150.0" linkage_crank_out="40.0"
+                                    linkage_alpha_zero="338.82213" linkage_sign="1"
+                                    use_linkage="${use_linkage}"/>
     <xacro:lite_biped_joint name="left_ankle_roll" can_id="37" model="rs-05" direction="-1"
-                      lower_limit="-0.349066" upper_limit="0.349066"
-                      torque_limit="5.5" current_limit="14"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="-0.349066" upper_limit="0.349066" torque_limit="5.5"
+                            current_limit="14"/>
   </xacro:macro>
 
-  <xacro:macro name="lite_biped_right_leg_joints" params="use_fake_hardware use_sim use_linkage:=true">
+  <xacro:macro name="lite_biped_right_leg_joints" params="use_linkage:=true">
     <xacro:lite_biped_joint name="right_hip_pitch" can_id="41" model="rs-06" direction="1"
-                      lower_limit="-2.35619" upper_limit="0.785398"
-                      torque_limit="36.0" current_limit="43"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="-2.35619" upper_limit="0.785398" torque_limit="36.0"
+                            current_limit="43"/>
     <xacro:lite_biped_joint name="right_hip_roll" can_id="42" model="rs-06" direction="1"
-                      lower_limit="-1.5708" upper_limit="0.349066"
-                      torque_limit="36.0" current_limit="43"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="-1.5708" upper_limit="0.349066" torque_limit="36.0"
+                            current_limit="43"/>
     <xacro:lite_biped_joint name="right_hip_yaw" can_id="43" model="rs-02" direction="1"
-                      lower_limit="-1.5708" upper_limit="1.5708"
-                      torque_limit="17.0" current_limit="27"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="-1.5708" upper_limit="1.5708" torque_limit="17.0"
+                            current_limit="27"/>
     <xacro:lite_biped_joint name="right_knee_pitch" can_id="44" model="rs-06" direction="1"
-                      lower_limit="0.0" upper_limit="2.35619"
-                      torque_limit="36.0" current_limit="43"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="0.0" upper_limit="2.35619" torque_limit="36.0"
+                            current_limit="43"/>
     <xacro:lite_biped_joint name="right_ankle_yaw" can_id="45" model="rs-00" direction="1"
-                      lower_limit="-1.5708" upper_limit="1.5708"
-                      torque_limit="14.0" current_limit="16"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
-    <xacro:lite_biped_joint name="right_ankle_pitch" can_id="46" model="rs-00" direction="-1"
-                      lower_limit="-0.523599" upper_limit="0.872665"
-                      torque_limit="14.0" current_limit="16"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"
-                      linkage_ground="160.449369" linkage_crank_in="40.0"
-                      linkage_coupler="150.0" linkage_crank_out="40.0"
-                      linkage_alpha_zero="338.82213" linkage_sign="1"
-                      use_linkage="${use_linkage}"/>
+                            lower_limit="-1.5708" upper_limit="1.5708" torque_limit="14.0"
+                            current_limit="16"/>
+    <xacro:lite_biped_linkage_joint name="right_ankle_pitch" can_id="46" model="rs-00"
+                                    direction="-1" lower_limit="-0.523599" upper_limit="0.872665"
+                                    torque_limit="14.0" current_limit="16"
+                                    linkage_ground="160.449369" linkage_crank_in="40.0"
+                                    linkage_coupler="150.0" linkage_crank_out="40.0"
+                                    linkage_alpha_zero="338.82213" linkage_sign="1"
+                                    use_linkage="${use_linkage}"/>
     <xacro:lite_biped_joint name="right_ankle_roll" can_id="47" model="rs-05" direction="-1"
-                      lower_limit="-0.349066" upper_limit="0.349066"
-                      torque_limit="5.5" current_limit="14"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="-0.349066" upper_limit="0.349066" torque_limit="5.5"
+                            current_limit="14"/>
   </xacro:macro>
 
-  <!-- Combined single-block layout for the sim and mock backends. -->
-  <xacro:macro name="lite_biped_ros2_control_combined" params="name use_fake_hardware use_sim">
+  <!-- Combined single block for the mock and MuJoCo backends. -->
+  <xacro:macro name="lite_biped_ros2_control_combined" params="name sim_mujoco">
     <ros2_control name="${name}" type="system">
       <hardware>
-        <xacro:if value="${use_sim}">
+        <xacro:if value="${sim_mujoco}">
           <plugin>mujoco_ros2_control/MujocoSystem</plugin>
         </xacro:if>
-        <xacro:unless value="${use_sim}">
+        <xacro:unless value="${sim_mujoco}">
           <plugin>mock_components/GenericSystem</plugin>
         </xacro:unless>
       </hardware>
-      <xacro:lite_biped_left_leg_joints use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
-      <xacro:lite_biped_right_leg_joints use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
-      <xacro:if value="${use_sim}">
+      <xacro:lite_biped_left_leg_joints/>
+      <xacro:lite_biped_right_leg_joints/>
+      <xacro:if value="${sim_mujoco}">
         <sensor name="base_imu">
           <state_interface name="orientation.x"/>
           <state_interface name="orientation.y"/>
@@ -151,18 +151,18 @@
     </ros2_control>
   </xacro:macro>
 
-  <!-- Real hardware: one <ros2_control> block per CAN bus (plus the base IMU
-       sensor). The controller_manager runs them concurrently and exposes a
-       single flat joint list to controllers. -->
+  <!-- Real hardware: one <ros2_control> block per CAN bus. The controller_manager
+       runs them concurrently and exposes a single flat joint list to controllers. -->
   <xacro:macro name="lite_biped_ros2_control_real"
-               params="mode can_interface_left can_interface_right calibration_file imu_port use_linkage">
+               params="can_interface_left can_interface_right calibration_file imu_port
+                       use_linkage">
     <ros2_control name="LiteBipedLeftLeg" type="system">
       <hardware>
         <plugin>humanoid_devices_robstride/RobstrideSystem</plugin>
         <param name="can_interface">${can_interface_left}</param>
         <param name="calibration_file">${calibration_file}</param>
       </hardware>
-      <xacro:lite_biped_left_leg_joints use_fake_hardware="false" use_sim="false" use_linkage="${use_linkage}"/>
+      <xacro:lite_biped_left_leg_joints use_linkage="${use_linkage}"/>
     </ros2_control>
     <ros2_control name="LiteBipedRightLeg" type="system">
       <hardware>
@@ -170,11 +170,11 @@
         <param name="can_interface">${can_interface_right}</param>
         <param name="calibration_file">${calibration_file}</param>
       </hardware>
-      <xacro:lite_biped_right_leg_joints use_fake_hardware="false" use_sim="false" use_linkage="${use_linkage}"/>
+      <xacro:lite_biped_right_leg_joints use_linkage="${use_linkage}"/>
     </ros2_control>
     <ros2_control name="LiteBipedIMU" type="sensor">
       <hardware>
-        <plugin>humanoid_devices_imu_hardware/YahboomImuSensor</plugin>
+        <plugin>humanoid_devices_witmotion/WitImuSensor</plugin>
         <param name="port">${imu_port}</param>
       </hardware>
       <sensor name="base_imu">
@@ -192,17 +192,17 @@
     </ros2_control>
   </xacro:macro>
 
-  <!-- Top-level dispatch: combined block for sim/mock, per-bus blocks for real
-       (use_sim wins over use_fake_hardware, matching franka_ros2 / UR precedence). -->
+  <!-- Backend dispatch, following the Universal Robots description convention: one
+       boolean per non-real backend, real hardware as the fallback when both are false.
+       sim_mujoco wins over use_mock_hardware. -->
   <xacro:macro name="lite_biped_ros2_control"
-               params="name use_fake_hardware use_sim mode
-                       can_interface_left can_interface_right calibration_file imu_port use_linkage">
-    <xacro:if value="${use_sim or use_fake_hardware}">
-      <xacro:lite_biped_ros2_control_combined name="${name}"
-        use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+               params="name use_mock_hardware sim_mujoco can_interface_left can_interface_right
+                       calibration_file imu_port use_linkage">
+    <xacro:if value="${sim_mujoco or use_mock_hardware}">
+      <xacro:lite_biped_ros2_control_combined name="${name}" sim_mujoco="${sim_mujoco}"/>
     </xacro:if>
-    <xacro:unless value="${use_sim or use_fake_hardware}">
-      <xacro:lite_biped_ros2_control_real mode="${mode}"
+    <xacro:unless value="${sim_mujoco or use_mock_hardware}">
+      <xacro:lite_biped_ros2_control_real
         can_interface_left="${can_interface_left}"
         can_interface_right="${can_interface_right}"
         calibration_file="${calibration_file}"
diff --git a/robots/lite_biped/xacro/lite_biped.urdf.xacro b/robots/lite_biped/xacro/lite_biped.urdf.xacro
index b4883f0..59931b3 100644
--- a/robots/lite_biped/xacro/lite_biped.urdf.xacro
+++ b/robots/lite_biped/xacro/lite_biped.urdf.xacro
@@ -1,9 +1,8 @@
 <?xml version="1.0"?>
 <!-- GENERATED by robot_assets from Onshape CAD. Do not edit by hand. Regenerate: robot-assets-generate lite_biped -->
 <robot xmlns:xacro="http://www.ros.org/wiki/xacro" name="lite_biped">
-  <xacro:arg name="use_fake_hardware" default="true"/>
-  <xacro:arg name="use_sim" default="false"/>
-  <xacro:arg name="mode" default="legs"/>
+  <xacro:arg name="use_mock_hardware" default="true"/>
+  <xacro:arg name="sim_mujoco" default="false"/>
   <xacro:arg name="can_interface_left" default="can2"/>
   <xacro:arg name="can_interface_right" default="can3"/>
   <xacro:arg name="calibration_file" default=""/>
@@ -17,9 +16,8 @@
 
   <xacro:lite_biped_ros2_control
     name="LiteBipedHardware"
-    use_fake_hardware="$(arg use_fake_hardware)"
-    use_sim="$(arg use_sim)"
-    mode="$(arg mode)"
+    use_mock_hardware="$(arg use_mock_hardware)"
+    sim_mujoco="$(arg sim_mujoco)"
     can_interface_left="$(arg can_interface_left)"
     can_interface_right="$(arg can_interface_right)"
     calibration_file="$(arg calibration_file)"
diff --git a/robots/lite_biped_debug/cad/ros2_control.json b/robots/lite_biped_debug/cad/ros2_control.json
index 15e833b..1db2f6f 100644
--- a/robots/lite_biped_debug/cad/ros2_control.json
+++ b/robots/lite_biped_debug/cad/ros2_control.json
@@ -1,5 +1,5 @@
 {
-    "_comment": "ROS 2 hardware mapping for the lite_biped_debug variant (legs-only floating-base humanoid; identical to lite_biped except for a simplified foot collider). Drives generation of xacro/lite_biped_debug.ros2_control.xacro. Joint position limits come from the URDF (single source). The sim/mock combined block also advertises a base IMU <sensor> (use_sim only), backed by the MJCF base_quat/base_gyro/base_accel sensors via MujocoSystem and republished by imu_sensor_broadcaster. real-hardware can_id set from a live bus scan (left can2 ids 31-37, right can3 ids 41-47); direction/current_limit still pending commissioning + leg calibration. ankle_pitch carries a FOUR-BAR linkage (actuator in the shin pushes a coupler to a crank on the foot): ground = sqrt(160^2+12^2) = 160.449369 mm (the actuator pivot is 160 above / 12 BEHIND the ankle pivot, so the ground link is NOT 160), cranks 40, coupler 150, alpha_zero 338.822130 deg, sign +1 -- verified against CAD (the coupler closes to 150.0000 mm at joint -30/0/+50). RobstrideSystem converts joint<->actuator through it and refers the commanded impedance by J^2. Pass use_linkage:=false for calibration, which needs raw actuator angles.",
+    "_comment": "ROS 2 hardware mapping for the lite_biped_debug variant (legs-only floating-base humanoid; identical to lite_biped except for a simplified foot collider). Drives generation of xacro/lite_biped_debug.ros2_control.xacro. Joint position limits come from the URDF (single source). The sim/mock combined block also advertises a base IMU <sensor> (sim_mujoco only), backed by the MJCF base_quat/base_gyro/base_accel sensors via MujocoSystem and republished by imu_sensor_broadcaster. real-hardware can_id set from a live bus scan (left can2 ids 31-37, right can3 ids 41-47); direction/current_limit still pending commissioning + leg calibration. ankle_pitch carries a FOUR-BAR linkage (actuator in the shin pushes a coupler to a crank on the foot): ground = sqrt(160^2+12^2) = 160.449369 mm (the actuator pivot is 160 above / 12 BEHIND the ankle pivot, so the ground link is NOT 160), cranks 40, coupler 150, alpha_zero 338.822130 deg, sign +1 -- verified against CAD (the coupler closes to 150.0000 mm at joint -30/0/+50). RobstrideSystem converts joint<->actuator through it and refers the commanded impedance by J^2. Pass use_linkage:=false for calibration, which needs raw actuator angles.",
 
     "interfaces": {
         "command": ["position", "velocity", "effort", "stiffness", "damping"],
@@ -13,9 +13,8 @@
     },
 
     "args": {
-        "use_fake_hardware": "true",
-        "use_sim": "false",
-        "mode": "legs",
+        "use_mock_hardware": "true",
+        "sim_mujoco": "false",
         "can_interface_left": "can2",
         "can_interface_right": "can3",
         "calibration_file": "",
@@ -28,17 +27,13 @@
     "combined_block_name": "LiteBipedHardware",
 
     "_comment_imu": "Sim/mock: the base_imu <sensor> lives in the combined block, backed by MujocoSystem's MJCF sensors. Real: a standalone <ros2_control type='sensor'> block (real_block_name) driven by real_plugin (Yahboom WIT USB IMU on imu_port), exposing the SAME interfaces so imu_sensor_broadcaster republishes /imu/data identically -- no separate driver node.",
-    "imu": {"name": "base_imu", "real_plugin": "humanoid_devices_imu_hardware/YahboomImuSensor", "real_block_name": "LiteBipedIMU"},
+    "imu": {"name": "base_imu", "real_plugin": "humanoid_devices_witmotion/WitImuSensor", "real_block_name": "LiteBipedIMU"},
 
     "groups": [
         {"name": "left_leg",  "block_name": "LiteBipedLeftLeg",  "can_interface_arg": "can_interface_left"},
         {"name": "right_leg", "block_name": "LiteBipedRightLeg", "can_interface_arg": "can_interface_right"}
     ],
 
-    "modes": {
-        "legs": ["left_leg", "right_leg"]
-    },
-
     "joints": [
         {"name": "left_hip_pitch",   "group": "left_leg",  "can_id": 31, "model": "rs-06", "direction": -1, "torque_limit": 36.0, "current_limit": 43},
         {"name": "left_hip_roll",    "group": "left_leg",  "can_id": 32, "model": "rs-06", "direction": 1, "torque_limit": 36.0, "current_limit": 43},
diff --git a/robots/lite_biped_debug/mjcf/lite_biped_debug.xml b/robots/lite_biped_debug/mjcf/lite_biped_debug.xml
index e6897a9..e34165f 100644
--- a/robots/lite_biped_debug/mjcf/lite_biped_debug.xml
+++ b/robots/lite_biped_debug/mjcf/lite_biped_debug.xml
@@ -2,8 +2,8 @@
 <mujoco model="lite_biped_debug">
   <!-- GENERATED by robot_assets from Onshape CAD. Do not edit by hand. Regenerate: robot-assets-generate lite_biped_debug -->
   <compiler angle="radian" meshdir="../meshes/visual/" />
-
-  <option timestep="0.005" integrator="implicitfast" solver="Newton" cone="pyramidal" impratio="1" iterations="10" ls_iterations="20" /><asset>
+  <option timestep="0.005" integrator="implicitfast" solver="Newton" cone="pyramidal" impratio="1" iterations="10" ls_iterations="20" />
+  <asset>
     <mesh name="pelvis_visual" content_type="model/stl" file="pelvis_visual.stl" />
     <mesh name="left_hip_pitch_visual" content_type="model/stl" file="left_hip_pitch_visual.stl" />
     <mesh name="left_hip_roll_visual" content_type="model/stl" file="left_hip_roll_visual.stl" />
@@ -20,7 +20,6 @@
     <mesh name="right_ankle_pitch_visual" content_type="model/stl" file="right_ankle_pitch_visual.stl" />
     <mesh name="right_foot_visual" content_type="model/stl" file="right_foot_visual.stl" />
   </asset>
-
   <worldbody>
     <body name="pelvis">
       <joint name="floating_base_joint" type="free" limited="false" actuatorfrclimited="false" /><site name="imu_site" pos="0.0 0.0 0.08" /><inertial pos="0.0137049 6.97587e-07 0.0692011" quat="0.999864 -1.34288e-05 0.0164944 1.28012e-05" mass="2.1" diaginertia="0.00988318 0.00823366 0.0063777" />
@@ -106,4 +105,27 @@
       </body>
     </body>
   </worldbody>
-<sensor><framequat name="base_quat" objtype="site" objname="imu_site" /><gyro name="base_gyro" site="imu_site" /><accelerometer name="base_accel" site="imu_site" /><velocimeter name="base_vel" site="imu_site" /><framepos name="base_pos" objtype="site" objname="imu_site" /></sensor><actuator><position name="left_hip_pitch" joint="left_hip_pitch" forcerange="-36.0 36.0" /><position name="left_hip_roll" joint="left_hip_roll" forcerange="-36.0 36.0" /><position name="left_hip_yaw" joint="left_hip_yaw" forcerange="-17.0 17.0" /><position name="left_knee_pitch" joint="left_knee_pitch" forcerange="-36.0 36.0" /><position name="left_ankle_yaw" joint="left_ankle_yaw" forcerange="-14.0 14.0" /><position name="left_ankle_pitch" joint="left_ankle_pitch" forcerange="-14.0 14.0" /><position name="left_ankle_roll" joint="left_ankle_roll" forcerange="-5.5 5.5" /><position name="right_hip_pitch" joint="right_hip_pitch" forcerange="-36.0 36.0" /><position name="right_hip_roll" joint="right_hip_roll" forcerange="-36.0 36.0" /><position name="right_hip_yaw" joint="right_hip_yaw" forcerange="-17.0 17.0" /><position name="right_knee_pitch" joint="right_knee_pitch" forcerange="-36.0 36.0" /><position name="right_ankle_yaw" joint="right_ankle_yaw" forcerange="-14.0 14.0" /><position name="right_ankle_pitch" joint="right_ankle_pitch" forcerange="-14.0 14.0" /><position name="right_ankle_roll" joint="right_ankle_roll" forcerange="-5.5 5.5" /></actuator></mujoco>
\ No newline at end of file
+  <sensor>
+    <framequat name="base_quat" objtype="site" objname="imu_site" />
+    <gyro name="base_gyro" site="imu_site" />
+    <accelerometer name="base_accel" site="imu_site" />
+    <velocimeter name="base_vel" site="imu_site" />
+    <framepos name="base_pos" objtype="site" objname="imu_site" />
+  </sensor>
+  <actuator>
+    <position name="left_hip_pitch" joint="left_hip_pitch" forcerange="-36.0 36.0" />
+    <position name="left_hip_roll" joint="left_hip_roll" forcerange="-36.0 36.0" />
+    <position name="left_hip_yaw" joint="left_hip_yaw" forcerange="-17.0 17.0" />
+    <position name="left_knee_pitch" joint="left_knee_pitch" forcerange="-36.0 36.0" />
+    <position name="left_ankle_yaw" joint="left_ankle_yaw" forcerange="-14.0 14.0" />
+    <position name="left_ankle_pitch" joint="left_ankle_pitch" forcerange="-14.0 14.0" />
+    <position name="left_ankle_roll" joint="left_ankle_roll" forcerange="-5.5 5.5" />
+    <position name="right_hip_pitch" joint="right_hip_pitch" forcerange="-36.0 36.0" />
+    <position name="right_hip_roll" joint="right_hip_roll" forcerange="-36.0 36.0" />
+    <position name="right_hip_yaw" joint="right_hip_yaw" forcerange="-17.0 17.0" />
+    <position name="right_knee_pitch" joint="right_knee_pitch" forcerange="-36.0 36.0" />
+    <position name="right_ankle_yaw" joint="right_ankle_yaw" forcerange="-14.0 14.0" />
+    <position name="right_ankle_pitch" joint="right_ankle_pitch" forcerange="-14.0 14.0" />
+    <position name="right_ankle_roll" joint="right_ankle_roll" forcerange="-5.5 5.5" />
+  </actuator>
+</mujoco>
\ No newline at end of file
diff --git a/robots/lite_biped_debug/xacro/lite_biped_debug.ros2_control.xacro b/robots/lite_biped_debug/xacro/lite_biped_debug.ros2_control.xacro
index 865ba6b..d172c32 100644
--- a/robots/lite_biped_debug/xacro/lite_biped_debug.ros2_control.xacro
+++ b/robots/lite_biped_debug/xacro/lite_biped_debug.ros2_control.xacro
@@ -3,14 +3,11 @@
 <robot xmlns:xacro="http://www.ros.org/wiki/xacro">
 
   <!-- One joint: 5 command + 3 state interfaces (MIT mode).
-       Real-only hardware params are emitted under xacro:unless (sim/mock ignore them). -->
+       The params are read by humanoid_devices_robstride. The mock and MuJoCo backends
+       ignore params they do not know, so this one macro serves all three. -->
   <xacro:macro name="lite_biped_debug_joint"
-               params="name can_id model direction
-                       lower_limit upper_limit torque_limit current_limit
-                       use_fake_hardware use_sim
-                       use_linkage:=true linkage_ground:=0
-                       linkage_crank_in:=0 linkage_coupler:=0 linkage_crank_out:=0
-                       linkage_alpha_zero:=0 linkage_sign:=1">
+               params="name can_id model direction lower_limit upper_limit torque_limit
+                       current_limit">
     <joint name="${name}">
       <command_interface name="position"/>
       <command_interface name="velocity"/>
@@ -20,121 +17,124 @@
       <state_interface name="position"/>
       <state_interface name="velocity"/>
       <state_interface name="effort"/>
-      <xacro:unless value="${use_sim or use_fake_hardware}">
-        <param name="can_id">${can_id}</param>
-        <param name="model">${model}</param>
-        <param name="direction">${direction}</param>
-        <param name="lower_limit">${lower_limit}</param>
-        <param name="upper_limit">${upper_limit}</param>
-        <param name="torque_limit">${torque_limit}</param>
-        <param name="current_limit">${current_limit}</param>
-        <!-- Four-bar transmission geometry, for joints that declare one in
-             ros2_control.json. The geometry is a PHYSICAL FACT so it is always
-             published: calibrate_robot reads it from /robot_description to refer
-             the URDF joint limits into actuator space, even on the runs where the
-             hardware plugin must NOT apply the transform. `linkage_enabled`
-             (= the use_linkage arg) is what switches the plugin's behaviour:
-             false during calibration, which needs raw actuator angles. With it
-             true, RobstrideSystem converts joint<->actuator through the linkage
-             and refers the commanded impedance by J^2, so /joint_states and every
-             controller speak true joint space. -->
-        <xacro:if value="${linkage_ground > 0}">
-          <param name="linkage_ground">${linkage_ground}</param>
-          <param name="linkage_crank_in">${linkage_crank_in}</param>
-          <param name="linkage_coupler">${linkage_coupler}</param>
-          <param name="linkage_crank_out">${linkage_crank_out}</param>
-          <param name="linkage_alpha_zero">${linkage_alpha_zero}</param>
-          <param name="linkage_sign">${linkage_sign}</param>
-          <param name="linkage_enabled">${use_linkage}</param>
-        </xacro:if>
-      </xacro:unless>
+      <param name="can_id">${can_id}</param>
+      <param name="model">${model}</param>
+      <param name="direction">${direction}</param>
+      <param name="lower_limit">${lower_limit}</param>
+      <param name="upper_limit">${upper_limit}</param>
+      <param name="torque_limit">${torque_limit}</param>
+      <param name="current_limit">${current_limit}</param>
+    </joint>
+  </xacro:macro>
+
+  <!-- A joint driven through a four-bar linkage, otherwise identical to
+       lite_biped_debug_joint. The geometry is a physical fact, so it is always published:
+       calibrate_robot reads it from /robot_description to refer the URDF joint limits into
+       actuator space even on the runs where the plugin must not apply the transform.
+       linkage_enabled is the switch for that. With it true, RobstrideSystem converts
+       joint<->actuator through the linkage and refers the commanded impedance by J^2, so
+       /joint_states and every controller speak true joint space. Calibration sets it
+       false, because it needs raw actuator angles. -->
+  <xacro:macro name="lite_biped_debug_linkage_joint"
+               params="name can_id model direction lower_limit upper_limit torque_limit
+                       current_limit linkage_ground linkage_crank_in linkage_coupler
+                       linkage_crank_out linkage_alpha_zero linkage_sign use_linkage">
+    <joint name="${name}">
+      <command_interface name="position"/>
+      <command_interface name="velocity"/>
+      <command_interface name="effort"/>
+      <command_interface name="stiffness"/>
+      <command_interface name="damping"/>
+      <state_interface name="position"/>
+      <state_interface name="velocity"/>
+      <state_interface name="effort"/>
+      <param name="can_id">${can_id}</param>
+      <param name="model">${model}</param>
+      <param name="direction">${direction}</param>
+      <param name="lower_limit">${lower_limit}</param>
+      <param name="upper_limit">${upper_limit}</param>
+      <param name="torque_limit">${torque_limit}</param>
+      <param name="current_limit">${current_limit}</param>
+      <param name="linkage_ground">${linkage_ground}</param>
+      <param name="linkage_crank_in">${linkage_crank_in}</param>
+      <param name="linkage_coupler">${linkage_coupler}</param>
+      <param name="linkage_crank_out">${linkage_crank_out}</param>
+      <param name="linkage_alpha_zero">${linkage_alpha_zero}</param>
+      <param name="linkage_sign">${linkage_sign}</param>
+      <param name="linkage_enabled">${use_linkage}</param>
     </joint>
   </xacro:macro>
 
-  <xacro:macro name="lite_biped_debug_left_leg_joints" params="use_fake_hardware use_sim use_linkage:=true">
+  <xacro:macro name="lite_biped_debug_left_leg_joints" params="use_linkage:=true">
     <xacro:lite_biped_debug_joint name="left_hip_pitch" can_id="31" model="rs-06" direction="-1"
-                      lower_limit="-2.35619" upper_limit="0.785398"
-                      torque_limit="36.0" current_limit="43"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                                  lower_limit="-2.35619" upper_limit="0.785398"
+                                  torque_limit="36.0" current_limit="43"/>
     <xacro:lite_biped_debug_joint name="left_hip_roll" can_id="32" model="rs-06" direction="1"
-                      lower_limit="-0.349066" upper_limit="1.5708"
-                      torque_limit="36.0" current_limit="43"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                                  lower_limit="-0.349066" upper_limit="1.5708" torque_limit="36.0"
+                                  current_limit="43"/>
     <xacro:lite_biped_debug_joint name="left_hip_yaw" can_id="33" model="rs-02" direction="1"
-                      lower_limit="-1.5708" upper_limit="1.5708"
-                      torque_limit="17.0" current_limit="27"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                                  lower_limit="-1.5708" upper_limit="1.5708" torque_limit="17.0"
+                                  current_limit="27"/>
     <xacro:lite_biped_debug_joint name="left_knee_pitch" can_id="34" model="rs-06" direction="-1"
-                      lower_limit="0.0" upper_limit="2.35619"
-                      torque_limit="36.0" current_limit="43"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                                  lower_limit="0.0" upper_limit="2.35619" torque_limit="36.0"
+                                  current_limit="43"/>
     <xacro:lite_biped_debug_joint name="left_ankle_yaw" can_id="35" model="rs-00" direction="1"
-                      lower_limit="-1.5708" upper_limit="1.5708"
-                      torque_limit="14.0" current_limit="16"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
-    <xacro:lite_biped_debug_joint name="left_ankle_pitch" can_id="36" model="rs-00" direction="1"
-                      lower_limit="-0.523599" upper_limit="0.872665"
-                      torque_limit="14.0" current_limit="16"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"
-                      linkage_ground="160.449369" linkage_crank_in="40.0"
-                      linkage_coupler="150.0" linkage_crank_out="40.0"
-                      linkage_alpha_zero="338.82213" linkage_sign="1"
-                      use_linkage="${use_linkage}"/>
+                                  lower_limit="-1.5708" upper_limit="1.5708" torque_limit="14.0"
+                                  current_limit="16"/>
+    <xacro:lite_biped_debug_linkage_joint name="left_ankle_pitch" can_id="36" model="rs-00"
+                                          direction="1" lower_limit="-0.523599"
+                                          upper_limit="0.872665" torque_limit="14.0"
+                                          current_limit="16" linkage_ground="160.449369"
+                                          linkage_crank_in="40.0" linkage_coupler="150.0"
+                                          linkage_crank_out="40.0" linkage_alpha_zero="338.82213"
+                                          linkage_sign="1" use_linkage="${use_linkage}"/>
     <xacro:lite_biped_debug_joint name="left_ankle_roll" can_id="37" model="rs-05" direction="-1"
-                      lower_limit="-0.349066" upper_limit="0.349066"
-                      torque_limit="5.5" current_limit="14"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                                  lower_limit="-0.349066" upper_limit="0.349066"
+                                  torque_limit="5.5" current_limit="14"/>
   </xacro:macro>
 
-  <xacro:macro name="lite_biped_debug_right_leg_joints" params="use_fake_hardware use_sim use_linkage:=true">
+  <xacro:macro name="lite_biped_debug_right_leg_joints" params="use_linkage:=true">
     <xacro:lite_biped_debug_joint name="right_hip_pitch" can_id="41" model="rs-06" direction="1"
-                      lower_limit="-2.35619" upper_limit="0.785398"
-                      torque_limit="36.0" current_limit="43"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                                  lower_limit="-2.35619" upper_limit="0.785398"
+                                  torque_limit="36.0" current_limit="43"/>
     <xacro:lite_biped_debug_joint name="right_hip_roll" can_id="42" model="rs-06" direction="1"
-                      lower_limit="-1.5708" upper_limit="0.349066"
-                      torque_limit="36.0" current_limit="43"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                                  lower_limit="-1.5708" upper_limit="0.349066" torque_limit="36.0"
+                                  current_limit="43"/>
     <xacro:lite_biped_debug_joint name="right_hip_yaw" can_id="43" model="rs-02" direction="1"
-                      lower_limit="-1.5708" upper_limit="1.5708"
-                      torque_limit="17.0" current_limit="27"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                                  lower_limit="-1.5708" upper_limit="1.5708" torque_limit="17.0"
+                                  current_limit="27"/>
     <xacro:lite_biped_debug_joint name="right_knee_pitch" can_id="44" model="rs-06" direction="1"
-                      lower_limit="0.0" upper_limit="2.35619"
-                      torque_limit="36.0" current_limit="43"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                                  lower_limit="0.0" upper_limit="2.35619" torque_limit="36.0"
+                                  current_limit="43"/>
     <xacro:lite_biped_debug_joint name="right_ankle_yaw" can_id="45" model="rs-00" direction="1"
-                      lower_limit="-1.5708" upper_limit="1.5708"
-                      torque_limit="14.0" current_limit="16"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
-    <xacro:lite_biped_debug_joint name="right_ankle_pitch" can_id="46" model="rs-00" direction="-1"
-                      lower_limit="-0.523599" upper_limit="0.872665"
-                      torque_limit="14.0" current_limit="16"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"
-                      linkage_ground="160.449369" linkage_crank_in="40.0"
-                      linkage_coupler="150.0" linkage_crank_out="40.0"
-                      linkage_alpha_zero="338.82213" linkage_sign="1"
-                      use_linkage="${use_linkage}"/>
+                                  lower_limit="-1.5708" upper_limit="1.5708" torque_limit="14.0"
+                                  current_limit="16"/>
+    <xacro:lite_biped_debug_linkage_joint name="right_ankle_pitch" can_id="46" model="rs-00"
+                                          direction="-1" lower_limit="-0.523599"
+                                          upper_limit="0.872665" torque_limit="14.0"
+                                          current_limit="16" linkage_ground="160.449369"
+                                          linkage_crank_in="40.0" linkage_coupler="150.0"
+                                          linkage_crank_out="40.0" linkage_alpha_zero="338.82213"
+                                          linkage_sign="1" use_linkage="${use_linkage}"/>
     <xacro:lite_biped_debug_joint name="right_ankle_roll" can_id="47" model="rs-05" direction="-1"
-                      lower_limit="-0.349066" upper_limit="0.349066"
-                      torque_limit="5.5" current_limit="14"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                                  lower_limit="-0.349066" upper_limit="0.349066"
+                                  torque_limit="5.5" current_limit="14"/>
   </xacro:macro>
 
-  <!-- Combined single-block layout for the sim and mock backends. -->
-  <xacro:macro name="lite_biped_debug_ros2_control_combined" params="name use_fake_hardware use_sim">
+  <!-- Combined single block for the mock and MuJoCo backends. -->
+  <xacro:macro name="lite_biped_debug_ros2_control_combined" params="name sim_mujoco">
     <ros2_control name="${name}" type="system">
       <hardware>
-        <xacro:if value="${use_sim}">
+        <xacro:if value="${sim_mujoco}">
           <plugin>mujoco_ros2_control/MujocoSystem</plugin>
         </xacro:if>
-        <xacro:unless value="${use_sim}">
+        <xacro:unless value="${sim_mujoco}">
           <plugin>mock_components/GenericSystem</plugin>
         </xacro:unless>
       </hardware>
-      <xacro:lite_biped_debug_left_leg_joints use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
-      <xacro:lite_biped_debug_right_leg_joints use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
-      <xacro:if value="${use_sim}">
+      <xacro:lite_biped_debug_left_leg_joints/>
+      <xacro:lite_biped_debug_right_leg_joints/>
+      <xacro:if value="${sim_mujoco}">
         <sensor name="base_imu">
           <state_interface name="orientation.x"/>
           <state_interface name="orientation.y"/>
@@ -151,18 +151,18 @@
     </ros2_control>
   </xacro:macro>
 
-  <!-- Real hardware: one <ros2_control> block per CAN bus (plus the base IMU
-       sensor). The controller_manager runs them concurrently and exposes a
-       single flat joint list to controllers. -->
+  <!-- Real hardware: one <ros2_control> block per CAN bus. The controller_manager
+       runs them concurrently and exposes a single flat joint list to controllers. -->
   <xacro:macro name="lite_biped_debug_ros2_control_real"
-               params="mode can_interface_left can_interface_right calibration_file imu_port use_linkage">
+               params="can_interface_left can_interface_right calibration_file imu_port
+                       use_linkage">
     <ros2_control name="LiteBipedLeftLeg" type="system">
       <hardware>
         <plugin>humanoid_devices_robstride/RobstrideSystem</plugin>
         <param name="can_interface">${can_interface_left}</param>
         <param name="calibration_file">${calibration_file}</param>
       </hardware>
-      <xacro:lite_biped_debug_left_leg_joints use_fake_hardware="false" use_sim="false" use_linkage="${use_linkage}"/>
+      <xacro:lite_biped_debug_left_leg_joints use_linkage="${use_linkage}"/>
     </ros2_control>
     <ros2_control name="LiteBipedRightLeg" type="system">
       <hardware>
@@ -170,11 +170,11 @@
         <param name="can_interface">${can_interface_right}</param>
         <param name="calibration_file">${calibration_file}</param>
       </hardware>
-      <xacro:lite_biped_debug_right_leg_joints use_fake_hardware="false" use_sim="false" use_linkage="${use_linkage}"/>
+      <xacro:lite_biped_debug_right_leg_joints use_linkage="${use_linkage}"/>
     </ros2_control>
     <ros2_control name="LiteBipedIMU" type="sensor">
       <hardware>
-        <plugin>humanoid_devices_imu_hardware/YahboomImuSensor</plugin>
+        <plugin>humanoid_devices_witmotion/WitImuSensor</plugin>
         <param name="port">${imu_port}</param>
       </hardware>
       <sensor name="base_imu">
@@ -192,17 +192,17 @@
     </ros2_control>
   </xacro:macro>
 
-  <!-- Top-level dispatch: combined block for sim/mock, per-bus blocks for real
-       (use_sim wins over use_fake_hardware, matching franka_ros2 / UR precedence). -->
+  <!-- Backend dispatch, following the Universal Robots description convention: one
+       boolean per non-real backend, real hardware as the fallback when both are false.
+       sim_mujoco wins over use_mock_hardware. -->
   <xacro:macro name="lite_biped_debug_ros2_control"
-               params="name use_fake_hardware use_sim mode
-                       can_interface_left can_interface_right calibration_file imu_port use_linkage">
-    <xacro:if value="${use_sim or use_fake_hardware}">
-      <xacro:lite_biped_debug_ros2_control_combined name="${name}"
-        use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+               params="name use_mock_hardware sim_mujoco can_interface_left can_interface_right
+                       calibration_file imu_port use_linkage">
+    <xacro:if value="${sim_mujoco or use_mock_hardware}">
+      <xacro:lite_biped_debug_ros2_control_combined name="${name}" sim_mujoco="${sim_mujoco}"/>
     </xacro:if>
-    <xacro:unless value="${use_sim or use_fake_hardware}">
-      <xacro:lite_biped_debug_ros2_control_real mode="${mode}"
+    <xacro:unless value="${sim_mujoco or use_mock_hardware}">
+      <xacro:lite_biped_debug_ros2_control_real
         can_interface_left="${can_interface_left}"
         can_interface_right="${can_interface_right}"
         calibration_file="${calibration_file}"
diff --git a/robots/lite_biped_debug/xacro/lite_biped_debug.urdf.xacro b/robots/lite_biped_debug/xacro/lite_biped_debug.urdf.xacro
index f4ec078..e465c5d 100644
--- a/robots/lite_biped_debug/xacro/lite_biped_debug.urdf.xacro
+++ b/robots/lite_biped_debug/xacro/lite_biped_debug.urdf.xacro
@@ -1,9 +1,8 @@
 <?xml version="1.0"?>
 <!-- GENERATED by robot_assets from Onshape CAD. Do not edit by hand. Regenerate: robot-assets-generate lite_biped_debug -->
 <robot xmlns:xacro="http://www.ros.org/wiki/xacro" name="lite_biped_debug">
-  <xacro:arg name="use_fake_hardware" default="true"/>
-  <xacro:arg name="use_sim" default="false"/>
-  <xacro:arg name="mode" default="legs"/>
+  <xacro:arg name="use_mock_hardware" default="true"/>
+  <xacro:arg name="sim_mujoco" default="false"/>
   <xacro:arg name="can_interface_left" default="can2"/>
   <xacro:arg name="can_interface_right" default="can3"/>
   <xacro:arg name="calibration_file" default=""/>
@@ -17,9 +16,8 @@
 
   <xacro:lite_biped_debug_ros2_control
     name="LiteBipedHardware"
-    use_fake_hardware="$(arg use_fake_hardware)"
-    use_sim="$(arg use_sim)"
-    mode="$(arg mode)"
+    use_mock_hardware="$(arg use_mock_hardware)"
+    sim_mujoco="$(arg sim_mujoco)"
     can_interface_left="$(arg can_interface_left)"
     can_interface_right="$(arg can_interface_right)"
     calibration_file="$(arg calibration_file)"
diff --git a/robots/lite_dummy/cad/ros2_control.json b/robots/lite_dummy/cad/ros2_control.json
index 8da6bd7..a598a56 100644
--- a/robots/lite_dummy/cad/ros2_control.json
+++ b/robots/lite_dummy/cad/ros2_control.json
@@ -13,9 +13,8 @@
     },
 
     "args": {
-        "use_fake_hardware": "true",
-        "use_sim": "false",
-        "mode": "arms",
+        "use_mock_hardware": "true",
+        "sim_mujoco": "false",
         "can_interface_left": "can0",
         "can_interface_right": "can1",
         "calibration_file": ""
@@ -25,18 +24,13 @@
 
     "combined_block_name": "LiteHardware",
 
+    "_comment_neck": "The neck actuators are not on the bus. Its kinematic links live in the description xacro for robot_state_publisher, but it gets no group and no joints here until the hardware is wired (CAN ids 31..33 by convention).",
+
     "groups": [
         {"name": "left_arm",  "block_name": "LiteLeftArm",  "can_interface_arg": "can_interface_left"},
-        {"name": "right_arm", "block_name": "LiteRightArm", "can_interface_arg": "can_interface_right"},
-        {"name": "neck",      "block_name": "LiteNeck",     "can_interface_arg": "can_interface_left", "stub": true,
-         "_comment": "Neck actuators were not on the bus during initial bringup. Kinematic neck links live in the description xacro for robot_state_publisher; populate this group's joints (CAN ids 31..33 by convention) when the hardware is wired."}
+        {"name": "right_arm", "block_name": "LiteRightArm", "can_interface_arg": "can_interface_right"}
     ],
 
-    "modes": {
-        "arms":      ["left_arm", "right_arm"],
-        "arms_neck": ["left_arm", "right_arm", "neck"]
-    },
-
     "joints": [
         {"name": "left_shoulder_pitch",  "group": "left_arm",  "can_id": 11, "model": "rs-02", "direction": -1, "torque_limit": 17,  "current_limit": 27},
         {"name": "left_shoulder_roll",   "group": "left_arm",  "can_id": 12, "model": "rs-00", "direction": -1, "torque_limit": 14,  "current_limit": 16},
diff --git a/robots/lite_dummy/mjcf/lite_dummy.xml b/robots/lite_dummy/mjcf/lite_dummy.xml
index b5cb98f..1a87ef3 100644
--- a/robots/lite_dummy/mjcf/lite_dummy.xml
+++ b/robots/lite_dummy/mjcf/lite_dummy.xml
@@ -2,8 +2,8 @@
 <mujoco model="lite">
   <!-- GENERATED by robot_assets from Onshape CAD. Do not edit by hand. Regenerate: robot-assets-generate lite_dummy -->
   <compiler angle="radian" meshdir="../meshes/visual/" />
-
-  <option timestep="0.001" integrator="implicitfast" solver="Newton" cone="elliptic" impratio="10" /><asset>
+  <option timestep="0.001" integrator="implicitfast" solver="Newton" cone="elliptic" impratio="10" />
+  <asset>
     <mesh name="chest_visual" content_type="model/stl" file="chest_visual.stl" />
     <mesh name="left_shoulder_pitch_visual" content_type="model/stl" file="left_shoulder_pitch_visual.stl" />
     <mesh name="left_shoulder_roll_visual" content_type="model/stl" file="left_shoulder_roll_visual.stl" />
@@ -23,7 +23,6 @@
     <mesh name="neck_roll_visual" content_type="model/stl" file="neck_roll_visual.stl" />
     <mesh name="head_visual" content_type="model/stl" file="head_visual.stl" />
   </asset>
-
   <worldbody>
     <body name="chest">
       <inertial pos="0.0229755 1.89075e-06 0.301247" quat="0.995694 2.09409e-05 -0.0926996 -0.00020815" mass="4.241" diaginertia="0.0300956 0.0293132 0.00962698" />
@@ -133,4 +132,23 @@
       </body>
     </body>
   </worldbody>
-<actuator><position name="left_shoulder_pitch" joint="left_shoulder_pitch" forcerange="-17 17" /><position name="left_shoulder_roll" joint="left_shoulder_roll" forcerange="-14 14" /><position name="left_shoulder_yaw" joint="left_shoulder_yaw" forcerange="-14 14" /><position name="left_elbow_pitch" joint="left_elbow_pitch" forcerange="-14 14" /><position name="left_wrist_yaw" joint="left_wrist_yaw" forcerange="-5.5 5.5" /><position name="left_wrist_roll" joint="left_wrist_roll" forcerange="-5.5 5.5" /><position name="left_wrist_pitch" joint="left_wrist_pitch" forcerange="-5.5 5.5" /><position name="right_shoulder_pitch" joint="right_shoulder_pitch" forcerange="-17 17" /><position name="right_shoulder_roll" joint="right_shoulder_roll" forcerange="-14 14" /><position name="right_shoulder_yaw" joint="right_shoulder_yaw" forcerange="-14 14" /><position name="right_elbow_pitch" joint="right_elbow_pitch" forcerange="-14 14" /><position name="right_wrist_yaw" joint="right_wrist_yaw" forcerange="-5.5 5.5" /><position name="right_wrist_roll" joint="right_wrist_roll" forcerange="-5.5 5.5" /><position name="right_wrist_pitch" joint="right_wrist_pitch" forcerange="-5.5 5.5" /><position name="neck_yaw" joint="neck_yaw" forcerange="-10 10" /><position name="neck_roll" joint="neck_roll" forcerange="-10 10" /><position name="neck_pitch" joint="neck_pitch" forcerange="-10 10" /></actuator></mujoco>
\ No newline at end of file
+  <actuator>
+    <position name="left_shoulder_pitch" joint="left_shoulder_pitch" forcerange="-17 17" />
+    <position name="left_shoulder_roll" joint="left_shoulder_roll" forcerange="-14 14" />
+    <position name="left_shoulder_yaw" joint="left_shoulder_yaw" forcerange="-14 14" />
+    <position name="left_elbow_pitch" joint="left_elbow_pitch" forcerange="-14 14" />
+    <position name="left_wrist_yaw" joint="left_wrist_yaw" forcerange="-5.5 5.5" />
+    <position name="left_wrist_roll" joint="left_wrist_roll" forcerange="-5.5 5.5" />
+    <position name="left_wrist_pitch" joint="left_wrist_pitch" forcerange="-5.5 5.5" />
+    <position name="right_shoulder_pitch" joint="right_shoulder_pitch" forcerange="-17 17" />
+    <position name="right_shoulder_roll" joint="right_shoulder_roll" forcerange="-14 14" />
+    <position name="right_shoulder_yaw" joint="right_shoulder_yaw" forcerange="-14 14" />
+    <position name="right_elbow_pitch" joint="right_elbow_pitch" forcerange="-14 14" />
+    <position name="right_wrist_yaw" joint="right_wrist_yaw" forcerange="-5.5 5.5" />
+    <position name="right_wrist_roll" joint="right_wrist_roll" forcerange="-5.5 5.5" />
+    <position name="right_wrist_pitch" joint="right_wrist_pitch" forcerange="-5.5 5.5" />
+    <position name="neck_yaw" joint="neck_yaw" forcerange="-10 10" />
+    <position name="neck_roll" joint="neck_roll" forcerange="-10 10" />
+    <position name="neck_pitch" joint="neck_pitch" forcerange="-10 10" />
+  </actuator>
+</mujoco>
\ No newline at end of file
diff --git a/robots/lite_dummy/xacro/lite_dummy.ros2_control.xacro b/robots/lite_dummy/xacro/lite_dummy.ros2_control.xacro
index d5f5f03..b56a450 100644
--- a/robots/lite_dummy/xacro/lite_dummy.ros2_control.xacro
+++ b/robots/lite_dummy/xacro/lite_dummy.ros2_control.xacro
@@ -3,11 +3,11 @@
 <robot xmlns:xacro="http://www.ros.org/wiki/xacro">
 
   <!-- One joint: 5 command + 3 state interfaces (MIT mode).
-       Real-only hardware params are emitted under xacro:unless (sim/mock ignore them). -->
+       The params are read by humanoid_devices_robstride. The mock and MuJoCo backends
+       ignore params they do not know, so this one macro serves all three. -->
   <xacro:macro name="lite_dummy_joint"
-               params="name can_id model direction
-                       lower_limit upper_limit torque_limit current_limit
-                       use_fake_hardware use_sim">
+               params="name can_id model direction lower_limit upper_limit torque_limit
+                       current_limit">
     <joint name="${name}">
       <command_interface name="position"/>
       <command_interface name="velocity"/>
@@ -17,112 +17,91 @@
       <state_interface name="position"/>
       <state_interface name="velocity"/>
       <state_interface name="effort"/>
-      <xacro:unless value="${use_sim or use_fake_hardware}">
-        <param name="can_id">${can_id}</param>
-        <param name="model">${model}</param>
-        <param name="direction">${direction}</param>
-        <param name="lower_limit">${lower_limit}</param>
-        <param name="upper_limit">${upper_limit}</param>
-        <param name="torque_limit">${torque_limit}</param>
-        <param name="current_limit">${current_limit}</param>
-      </xacro:unless>
+      <param name="can_id">${can_id}</param>
+      <param name="model">${model}</param>
+      <param name="direction">${direction}</param>
+      <param name="lower_limit">${lower_limit}</param>
+      <param name="upper_limit">${upper_limit}</param>
+      <param name="torque_limit">${torque_limit}</param>
+      <param name="current_limit">${current_limit}</param>
     </joint>
   </xacro:macro>
 
-  <xacro:macro name="lite_dummy_left_arm_joints" params="use_fake_hardware use_sim">
+  <xacro:macro name="lite_dummy_left_arm_joints">
     <xacro:lite_dummy_joint name="left_shoulder_pitch" can_id="11" model="rs-02" direction="-1"
-                      lower_limit="-3.14159" upper_limit="0.785398"
-                      torque_limit="17" current_limit="27"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="-3.14159" upper_limit="0.785398" torque_limit="17"
+                            current_limit="27"/>
     <xacro:lite_dummy_joint name="left_shoulder_roll" can_id="12" model="rs-00" direction="-1"
-                      lower_limit="-1.5708" upper_limit="1.91986"
-                      torque_limit="14" current_limit="16"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="-1.5708" upper_limit="1.91986" torque_limit="14"
+                            current_limit="16"/>
     <xacro:lite_dummy_joint name="left_shoulder_yaw" can_id="13" model="rs-00" direction="1"
-                      lower_limit="-1.5708" upper_limit="1.5708"
-                      torque_limit="14" current_limit="16"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="-1.5708" upper_limit="1.5708" torque_limit="14"
+                            current_limit="16"/>
     <xacro:lite_dummy_joint name="left_elbow_pitch" can_id="14" model="rs-00" direction="-1"
-                      lower_limit="-2.35619" upper_limit="0.0"
-                      torque_limit="14" current_limit="16"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="-2.35619" upper_limit="0.0" torque_limit="14"
+                            current_limit="16"/>
     <xacro:lite_dummy_joint name="left_wrist_yaw" can_id="15" model="rs-05" direction="1"
-                      lower_limit="-1.5708" upper_limit="1.5708"
-                      torque_limit="4.0" current_limit="14"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="-1.5708" upper_limit="1.5708" torque_limit="4.0"
+                            current_limit="14"/>
     <xacro:lite_dummy_joint name="left_wrist_roll" can_id="16" model="rs-05" direction="-1"
-                      lower_limit="-0.698132" upper_limit="0.698132"
-                      torque_limit="4.0" current_limit="14"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="-0.698132" upper_limit="0.698132" torque_limit="4.0"
+                            current_limit="14"/>
     <xacro:lite_dummy_joint name="left_wrist_pitch" can_id="17" model="rs-05" direction="-1"
-                      lower_limit="-0.785398" upper_limit="0.785398"
-                      torque_limit="4.0" current_limit="14"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="-0.785398" upper_limit="0.785398" torque_limit="4.0"
+                            current_limit="14"/>
   </xacro:macro>
 
-  <xacro:macro name="lite_dummy_right_arm_joints" params="use_fake_hardware use_sim">
+  <xacro:macro name="lite_dummy_right_arm_joints">
     <xacro:lite_dummy_joint name="right_shoulder_pitch" can_id="21" model="rs-02" direction="1"
-                      lower_limit="-3.14159" upper_limit="0.785398"
-                      torque_limit="17" current_limit="27"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="-3.14159" upper_limit="0.785398" torque_limit="17"
+                            current_limit="27"/>
     <xacro:lite_dummy_joint name="right_shoulder_roll" can_id="22" model="rs-00" direction="-1"
-                      lower_limit="-1.91986" upper_limit="1.5708"
-                      torque_limit="14" current_limit="16"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="-1.91986" upper_limit="1.5708" torque_limit="14"
+                            current_limit="16"/>
     <xacro:lite_dummy_joint name="right_shoulder_yaw" can_id="23" model="rs-00" direction="1"
-                      lower_limit="-1.5708" upper_limit="1.5708"
-                      torque_limit="14" current_limit="16"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="-1.5708" upper_limit="1.5708" torque_limit="14"
+                            current_limit="16"/>
     <xacro:lite_dummy_joint name="right_elbow_pitch" can_id="24" model="rs-00" direction="1"
-                      lower_limit="-2.35619" upper_limit="0.0"
-                      torque_limit="14" current_limit="16"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="-2.35619" upper_limit="0.0" torque_limit="14"
+                            current_limit="16"/>
     <xacro:lite_dummy_joint name="right_wrist_yaw" can_id="25" model="rs-05" direction="1"
-                      lower_limit="-1.5708" upper_limit="1.5708"
-                      torque_limit="4.0" current_limit="14"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="-1.5708" upper_limit="1.5708" torque_limit="4.0"
+                            current_limit="14"/>
     <xacro:lite_dummy_joint name="right_wrist_roll" can_id="26" model="rs-05" direction="1"
-                      lower_limit="-0.698132" upper_limit="0.698132"
-                      torque_limit="4.0" current_limit="14"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="-0.698132" upper_limit="0.698132" torque_limit="4.0"
+                            current_limit="14"/>
     <xacro:lite_dummy_joint name="right_wrist_pitch" can_id="27" model="rs-05" direction="-1"
-                      lower_limit="-0.785398" upper_limit="0.785398"
-                      torque_limit="4.0" current_limit="14"
-                      use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+                            lower_limit="-0.785398" upper_limit="0.785398" torque_limit="4.0"
+                            current_limit="14"/>
   </xacro:macro>
 
-  <!-- neck: stub. Populate when the CAN ids / model codes are confirmed on hardware. -->
-  <xacro:macro name="lite_dummy_neck_joints" params="use_fake_hardware use_sim">
-    <!-- TODO: neck joint declarations land here. -->
-  </xacro:macro>
-
-  <!-- Combined single-block layout for the sim and mock backends. -->
-  <xacro:macro name="lite_dummy_ros2_control_combined" params="name use_fake_hardware use_sim">
+  <!-- Combined single block for the mock and MuJoCo backends. -->
+  <xacro:macro name="lite_dummy_ros2_control_combined" params="name sim_mujoco">
     <ros2_control name="${name}" type="system">
       <hardware>
-        <xacro:if value="${use_sim}">
+        <xacro:if value="${sim_mujoco}">
           <plugin>mujoco_ros2_control/MujocoSystem</plugin>
         </xacro:if>
-        <xacro:unless value="${use_sim}">
+        <xacro:unless value="${sim_mujoco}">
           <plugin>mock_components/GenericSystem</plugin>
         </xacro:unless>
       </hardware>
-      <xacro:lite_dummy_left_arm_joints use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
-      <xacro:lite_dummy_right_arm_joints use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+      <xacro:lite_dummy_left_arm_joints/>
+      <xacro:lite_dummy_right_arm_joints/>
     </ros2_control>
   </xacro:macro>
 
   <!-- Real hardware: one <ros2_control> block per CAN bus. The controller_manager
        runs them concurrently and exposes a single flat joint list to controllers. -->
   <xacro:macro name="lite_dummy_ros2_control_real"
-               params="mode can_interface_left can_interface_right calibration_file">
+               params="can_interface_left can_interface_right calibration_file">
     <ros2_control name="LiteLeftArm" type="system">
       <hardware>
         <plugin>humanoid_devices_robstride/RobstrideSystem</plugin>
         <param name="can_interface">${can_interface_left}</param>
         <param name="calibration_file">${calibration_file}</param>
       </hardware>
-      <xacro:lite_dummy_left_arm_joints use_fake_hardware="false" use_sim="false"/>
+      <xacro:lite_dummy_left_arm_joints/>
     </ros2_control>
     <ros2_control name="LiteRightArm" type="system">
       <hardware>
@@ -130,32 +109,21 @@
         <param name="can_interface">${can_interface_right}</param>
         <param name="calibration_file">${calibration_file}</param>
       </hardware>
-      <xacro:lite_dummy_right_arm_joints use_fake_hardware="false" use_sim="false"/>
+      <xacro:lite_dummy_right_arm_joints/>
     </ros2_control>
-    <!-- neck bus: only with mode=arms_neck; stub until the actuators are wired. -->
-    <xacro:if value="${mode == 'arms_neck'}">
-      <ros2_control name="LiteNeck" type="system">
-        <hardware>
-          <plugin>humanoid_devices_robstride/RobstrideSystem</plugin>
-          <param name="can_interface">${can_interface_left}</param>
-          <param name="calibration_file">${calibration_file}</param>
-        </hardware>
-        <xacro:lite_dummy_neck_joints use_fake_hardware="false" use_sim="false"/>
-      </ros2_control>
-    </xacro:if>
   </xacro:macro>
 
-  <!-- Top-level dispatch: combined block for sim/mock, per-bus blocks for real
-       (use_sim wins over use_fake_hardware, matching franka_ros2 / UR precedence). -->
+  <!-- Backend dispatch, following the Universal Robots description convention: one
+       boolean per non-real backend, real hardware as the fallback when both are false.
+       sim_mujoco wins over use_mock_hardware. -->
   <xacro:macro name="lite_dummy_ros2_control"
-               params="name use_fake_hardware use_sim mode
-                       can_interface_left can_interface_right calibration_file">
-    <xacro:if value="${use_sim or use_fake_hardware}">
-      <xacro:lite_dummy_ros2_control_combined name="${name}"
-        use_fake_hardware="${use_fake_hardware}" use_sim="${use_sim}"/>
+               params="name use_mock_hardware sim_mujoco can_interface_left can_interface_right
+                       calibration_file">
+    <xacro:if value="${sim_mujoco or use_mock_hardware}">
+      <xacro:lite_dummy_ros2_control_combined name="${name}" sim_mujoco="${sim_mujoco}"/>
     </xacro:if>
-    <xacro:unless value="${use_sim or use_fake_hardware}">
-      <xacro:lite_dummy_ros2_control_real mode="${mode}"
+    <xacro:unless value="${sim_mujoco or use_mock_hardware}">
+      <xacro:lite_dummy_ros2_control_real
         can_interface_left="${can_interface_left}"
         can_interface_right="${can_interface_right}"
         calibration_file="${calibration_file}"/>
diff --git a/robots/lite_dummy/xacro/lite_dummy.urdf.xacro b/robots/lite_dummy/xacro/lite_dummy.urdf.xacro
index 699ab91..b2dcabf 100644
--- a/robots/lite_dummy/xacro/lite_dummy.urdf.xacro
+++ b/robots/lite_dummy/xacro/lite_dummy.urdf.xacro
@@ -1,9 +1,8 @@
 <?xml version="1.0"?>
 <!-- GENERATED by robot_assets from Onshape CAD. Do not edit by hand. Regenerate: robot-assets-generate lite_dummy -->
 <robot xmlns:xacro="http://www.ros.org/wiki/xacro" name="lite_dummy">
-  <xacro:arg name="use_fake_hardware" default="true"/>
-  <xacro:arg name="use_sim" default="false"/>
-  <xacro:arg name="mode" default="arms"/>
+  <xacro:arg name="use_mock_hardware" default="true"/>
+  <xacro:arg name="sim_mujoco" default="false"/>
   <xacro:arg name="can_interface_left" default="can0"/>
   <xacro:arg name="can_interface_right" default="can1"/>
   <xacro:arg name="calibration_file" default=""/>
@@ -15,9 +14,8 @@
 
   <xacro:lite_dummy_ros2_control
     name="LiteHardware"
-    use_fake_hardware="$(arg use_fake_hardware)"
-    use_sim="$(arg use_sim)"
-    mode="$(arg mode)"
+    use_mock_hardware="$(arg use_mock_hardware)"
+    sim_mujoco="$(arg sim_mujoco)"
     can_interface_left="$(arg can_interface_left)"
     can_interface_right="$(arg can_interface_right)"
     calibration_file="$(arg calibration_file)"/>
diff --git a/robots/lite_pro/mjcf/lite_pro.xml b/robots/lite_pro/mjcf/lite_pro.xml
index 2d0df01..29ee3fd 100644
--- a/robots/lite_pro/mjcf/lite_pro.xml
+++ b/robots/lite_pro/mjcf/lite_pro.xml
@@ -2,7 +2,6 @@
 <mujoco model="lite_pro">
   <!-- GENERATED by robot_assets from Onshape CAD. Do not edit by hand. Regenerate: robot-assets-generate lite_pro -->
   <compiler angle="radian" meshdir="../meshes/visual/" />
-
   <asset>
     <mesh name="pelvis_visual" content_type="model/stl" file="pelvis_visual.stl" />
     <mesh name="left_hip_pitch_visual" content_type="model/stl" file="left_hip_pitch_visual.stl" />
@@ -80,7 +79,6 @@
     <mesh name="neck_roll_visual" content_type="model/stl" file="neck_roll_visual.stl" />
     <mesh name="head_visual" content_type="model/stl" file="head_visual.stl" />
   </asset>
-
   <worldbody>
     <body name="pelvis">
       <inertial pos="0.0135183 5.78646e-07 0.0691358" quat="0.999848 -1.33806e-05 0.0174073 1.226e-05" mass="3.97182" diaginertia="0.0186941 0.015546 0.0121291" />
@@ -474,4 +472,80 @@
       </body>
     </body>
   </worldbody>
-<actuator><position name="left_hip_pitch" joint="left_hip_pitch" forcerange="-97.0 97.0" /><position name="left_hip_roll" joint="left_hip_roll" forcerange="-97.0 97.0" /><position name="left_hip_yaw" joint="left_hip_yaw" forcerange="-27.0 27.0" /><position name="left_knee_pitch" joint="left_knee_pitch" forcerange="-97.0 97.0" /><position name="left_ankle_yaw" joint="left_ankle_yaw" forcerange="-27.0 27.0" /><position name="left_ankle_pitch" joint="left_ankle_pitch" forcerange="-27.0 27.0" /><position name="left_ankle_roll" joint="left_ankle_roll" forcerange="-5.5 5.5" /><position name="right_hip_pitch" joint="right_hip_pitch" forcerange="-97.0 97.0" /><position name="right_hip_roll" joint="right_hip_roll" forcerange="-97.0 97.0" /><position name="right_hip_yaw" joint="right_hip_yaw" forcerange="-27.0 27.0" /><position name="right_knee_pitch" joint="right_knee_pitch" forcerange="-97.0 97.0" /><position name="right_ankle_yaw" joint="right_ankle_yaw" forcerange="-27.0 27.0" /><position name="right_ankle_pitch" joint="right_ankle_pitch" forcerange="-27.0 27.0" /><position name="right_ankle_roll" joint="right_ankle_roll" forcerange="-5.5 5.5" /><position name="waist_yaw" joint="waist_yaw" forcerange="-97.0 97.0" /><position name="waist_roll" joint="waist_roll" forcerange="-27.0 27.0" /><position name="waist_pitch" joint="waist_pitch" forcerange="-27.0 27.0" /><position name="left_shoulder_pitch" joint="left_shoulder_pitch" forcerange="-17.0 17.0" /><position name="left_shoulder_roll" joint="left_shoulder_roll" forcerange="-14.0 14.0" /><position name="left_shoulder_yaw" joint="left_shoulder_yaw" forcerange="-14.0 14.0" /><position name="left_elbow_pitch" joint="left_elbow_pitch" forcerange="-14.0 14.0" /><position name="left_wrist_yaw" joint="left_wrist_yaw" forcerange="-5.5 5.5" /><position name="left_wrist_roll" joint="left_wrist_roll" forcerange="-5.5 5.5" /><position name="left_wrist_pitch" joint="left_wrist_pitch" forcerange="-5.5 5.5" /><position name="left_finger1_j1" joint="left_finger1_j1" forcerange="-10 10" /><position name="left_finger1_j2" joint="left_finger1_j2" forcerange="-10 10" /><position name="left_finger1_j3" joint="left_finger1_j3" forcerange="-10 10" /><position name="left_finger1_j4" joint="left_finger1_j4" forcerange="-10 10" /><position name="left_finger2_j1" joint="left_finger2_j1" forcerange="-10 10" /><position name="left_finger2_j2" joint="left_finger2_j2" forcerange="-10 10" /><position name="left_finger2_j3" joint="left_finger2_j3" forcerange="-10 10" /><position name="left_finger2_j4" joint="left_finger2_j4" forcerange="-10 10" /><position name="left_finger3_j1" joint="left_finger3_j1" forcerange="-10 10" /><position name="left_finger3_j2" joint="left_finger3_j2" forcerange="-10 10" /><position name="left_finger3_j3" joint="left_finger3_j3" forcerange="-10 10" /><position name="left_finger3_j4" joint="left_finger3_j4" forcerange="-10 10" /><position name="left_finger4_j1" joint="left_finger4_j1" forcerange="-10 10" /><position name="left_finger4_j2" joint="left_finger4_j2" forcerange="-10 10" /><position name="left_finger4_j3" joint="left_finger4_j3" forcerange="-10 10" /><position name="left_finger4_j4" joint="left_finger4_j4" forcerange="-10 10" /><position name="left_finger5_j1" joint="left_finger5_j1" forcerange="-10 10" /><position name="left_finger5_j2" joint="left_finger5_j2" forcerange="-10 10" /><position name="left_finger5_j3" joint="left_finger5_j3" forcerange="-10 10" /><position name="left_finger5_j4" joint="left_finger5_j4" forcerange="-10 10" /><position name="right_shoulder_pitch" joint="right_shoulder_pitch" forcerange="-17.0 17.0" /><position name="right_shoulder_roll" joint="right_shoulder_roll" forcerange="-14.0 14.0" /><position name="right_shoulder_yaw" joint="right_shoulder_yaw" forcerange="-14.0 14.0" /><position name="right_elbow_pitch" joint="right_elbow_pitch" forcerange="-14.0 14.0" /><position name="right_wrist_yaw" joint="right_wrist_yaw" forcerange="-5.5 5.5" /><position name="right_wrist_roll" joint="right_wrist_roll" forcerange="-5.5 5.5" /><position name="right_wrist_pitch" joint="right_wrist_pitch" forcerange="-5.5 5.5" /><position name="right_finger1_j1" joint="right_finger1_j1" forcerange="-10 10" /><position name="right_finger1_j2" joint="right_finger1_j2" forcerange="-10 10" /><position name="right_finger1_j3" joint="right_finger1_j3" forcerange="-10 10" /><position name="right_finger1_j4" joint="right_finger1_j4" forcerange="-10 10" /><position name="right_finger2_j1" joint="right_finger2_j1" forcerange="-10 10" /><position name="right_finger2_j2" joint="right_finger2_j2" forcerange="-10 10" /><position name="right_finger2_j3" joint="right_finger2_j3" forcerange="-10 10" /><position name="right_finger2_j4" joint="right_finger2_j4" forcerange="-10 10" /><position name="right_finger3_j1" joint="right_finger3_j1" forcerange="-10 10" /><position name="right_finger3_j2" joint="right_finger3_j2" forcerange="-10 10" /><position name="right_finger3_j3" joint="right_finger3_j3" forcerange="-10 10" /><position name="right_finger3_j4" joint="right_finger3_j4" forcerange="-10 10" /><position name="right_finger4_j1" joint="right_finger4_j1" forcerange="-10 10" /><position name="right_finger4_j2" joint="right_finger4_j2" forcerange="-10 10" /><position name="right_finger4_j3" joint="right_finger4_j3" forcerange="-10 10" /><position name="right_finger4_j4" joint="right_finger4_j4" forcerange="-10 10" /><position name="right_finger5_j1" joint="right_finger5_j1" forcerange="-10 10" /><position name="right_finger5_j2" joint="right_finger5_j2" forcerange="-10 10" /><position name="right_finger5_j3" joint="right_finger5_j3" forcerange="-10 10" /><position name="right_finger5_j4" joint="right_finger5_j4" forcerange="-10 10" /><position name="neck_yaw" joint="neck_yaw" forcerange="-4.8 4.8" /><position name="neck_roll" joint="neck_roll" forcerange="-4.8 4.8" /><position name="neck_pitch" joint="neck_pitch" forcerange="-4.8 4.8" /></actuator></mujoco>
\ No newline at end of file
+  <actuator>
+    <position name="left_hip_pitch" joint="left_hip_pitch" forcerange="-97.0 97.0" />
+    <position name="left_hip_roll" joint="left_hip_roll" forcerange="-97.0 97.0" />
+    <position name="left_hip_yaw" joint="left_hip_yaw" forcerange="-27.0 27.0" />
+    <position name="left_knee_pitch" joint="left_knee_pitch" forcerange="-97.0 97.0" />
+    <position name="left_ankle_yaw" joint="left_ankle_yaw" forcerange="-27.0 27.0" />
+    <position name="left_ankle_pitch" joint="left_ankle_pitch" forcerange="-27.0 27.0" />
+    <position name="left_ankle_roll" joint="left_ankle_roll" forcerange="-5.5 5.5" />
+    <position name="right_hip_pitch" joint="right_hip_pitch" forcerange="-97.0 97.0" />
+    <position name="right_hip_roll" joint="right_hip_roll" forcerange="-97.0 97.0" />
+    <position name="right_hip_yaw" joint="right_hip_yaw" forcerange="-27.0 27.0" />
+    <position name="right_knee_pitch" joint="right_knee_pitch" forcerange="-97.0 97.0" />
+    <position name="right_ankle_yaw" joint="right_ankle_yaw" forcerange="-27.0 27.0" />
+    <position name="right_ankle_pitch" joint="right_ankle_pitch" forcerange="-27.0 27.0" />
+    <position name="right_ankle_roll" joint="right_ankle_roll" forcerange="-5.5 5.5" />
+    <position name="waist_yaw" joint="waist_yaw" forcerange="-97.0 97.0" />
+    <position name="waist_roll" joint="waist_roll" forcerange="-27.0 27.0" />
+    <position name="waist_pitch" joint="waist_pitch" forcerange="-27.0 27.0" />
+    <position name="left_shoulder_pitch" joint="left_shoulder_pitch" forcerange="-17.0 17.0" />
+    <position name="left_shoulder_roll" joint="left_shoulder_roll" forcerange="-14.0 14.0" />
+    <position name="left_shoulder_yaw" joint="left_shoulder_yaw" forcerange="-14.0 14.0" />
+    <position name="left_elbow_pitch" joint="left_elbow_pitch" forcerange="-14.0 14.0" />
+    <position name="left_wrist_yaw" joint="left_wrist_yaw" forcerange="-5.5 5.5" />
+    <position name="left_wrist_roll" joint="left_wrist_roll" forcerange="-5.5 5.5" />
+    <position name="left_wrist_pitch" joint="left_wrist_pitch" forcerange="-5.5 5.5" />
+    <position name="left_finger1_j1" joint="left_finger1_j1" forcerange="-10 10" />
+    <position name="left_finger1_j2" joint="left_finger1_j2" forcerange="-10 10" />
+    <position name="left_finger1_j3" joint="left_finger1_j3" forcerange="-10 10" />
+    <position name="left_finger1_j4" joint="left_finger1_j4" forcerange="-10 10" />
+    <position name="left_finger2_j1" joint="left_finger2_j1" forcerange="-10 10" />
+    <position name="left_finger2_j2" joint="left_finger2_j2" forcerange="-10 10" />
+    <position name="left_finger2_j3" joint="left_finger2_j3" forcerange="-10 10" />
+    <position name="left_finger2_j4" joint="left_finger2_j4" forcerange="-10 10" />
+    <position name="left_finger3_j1" joint="left_finger3_j1" forcerange="-10 10" />
+    <position name="left_finger3_j2" joint="left_finger3_j2" forcerange="-10 10" />
+    <position name="left_finger3_j3" joint="left_finger3_j3" forcerange="-10 10" />
+    <position name="left_finger3_j4" joint="left_finger3_j4" forcerange="-10 10" />
+    <position name="left_finger4_j1" joint="left_finger4_j1" forcerange="-10 10" />
+    <position name="left_finger4_j2" joint="left_finger4_j2" forcerange="-10 10" />
+    <position name="left_finger4_j3" joint="left_finger4_j3" forcerange="-10 10" />
+    <position name="left_finger4_j4" joint="left_finger4_j4" forcerange="-10 10" />
+    <position name="left_finger5_j1" joint="left_finger5_j1" forcerange="-10 10" />
+    <position name="left_finger5_j2" joint="left_finger5_j2" forcerange="-10 10" />
+    <position name="left_finger5_j3" joint="left_finger5_j3" forcerange="-10 10" />
+    <position name="left_finger5_j4" joint="left_finger5_j4" forcerange="-10 10" />
+    <position name="right_shoulder_pitch" joint="right_shoulder_pitch" forcerange="-17.0 17.0" />
+    <position name="right_shoulder_roll" joint="right_shoulder_roll" forcerange="-14.0 14.0" />
+    <position name="right_shoulder_yaw" joint="right_shoulder_yaw" forcerange="-14.0 14.0" />
+    <position name="right_elbow_pitch" joint="right_elbow_pitch" forcerange="-14.0 14.0" />
+    <position name="right_wrist_yaw" joint="right_wrist_yaw" forcerange="-5.5 5.5" />
+    <position name="right_wrist_roll" joint="right_wrist_roll" forcerange="-5.5 5.5" />
+    <position name="right_wrist_pitch" joint="right_wrist_pitch" forcerange="-5.5 5.5" />
+    <position name="right_finger1_j1" joint="right_finger1_j1" forcerange="-10 10" />
+    <position name="right_finger1_j2" joint="right_finger1_j2" forcerange="-10 10" />
+    <position name="right_finger1_j3" joint="right_finger1_j3" forcerange="-10 10" />
+    <position name="right_finger1_j4" joint="right_finger1_j4" forcerange="-10 10" />
+    <position name="right_finger2_j1" joint="right_finger2_j1" forcerange="-10 10" />
+    <position name="right_finger2_j2" joint="right_finger2_j2" forcerange="-10 10" />
+    <position name="right_finger2_j3" joint="right_finger2_j3" forcerange="-10 10" />
+    <position name="right_finger2_j4" joint="right_finger2_j4" forcerange="-10 10" />
+    <position name="right_finger3_j1" joint="right_finger3_j1" forcerange="-10 10" />
+    <position name="right_finger3_j2" joint="right_finger3_j2" forcerange="-10 10" />
+    <position name="right_finger3_j3" joint="right_finger3_j3" forcerange="-10 10" />
+    <position name="right_finger3_j4" joint="right_finger3_j4" forcerange="-10 10" />
+    <position name="right_finger4_j1" joint="right_finger4_j1" forcerange="-10 10" />
+    <position name="right_finger4_j2" joint="right_finger4_j2" forcerange="-10 10" />
+    <position name="right_finger4_j3" joint="right_finger4_j3" forcerange="-10 10" />
+    <position name="right_finger4_j4" joint="right_finger4_j4" forcerange="-10 10" />
+    <position name="right_finger5_j1" joint="right_finger5_j1" forcerange="-10 10" />
+    <position name="right_finger5_j2" joint="right_finger5_j2" forcerange="-10 10" />
+    <position name="right_finger5_j3" joint="right_finger5_j3" forcerange="-10 10" />
+    <position name="right_finger5_j4" joint="right_finger5_j4" forcerange="-10 10" />
+    <position name="neck_yaw" joint="neck_yaw" forcerange="-4.8 4.8" />
+    <position name="neck_roll" joint="neck_roll" forcerange="-4.8 4.8" />
+    <position name="neck_pitch" joint="neck_pitch" forcerange="-4.8 4.8" />
+  </actuator>
+</mujoco>
\ No newline at end of file
diff --git a/tests/test_ros2_artifacts.py b/tests/test_ros2_artifacts.py
index 775805e..b1d39c2 100644
--- a/tests/test_ros2_artifacts.py
+++ b/tests/test_ros2_artifacts.py
@@ -84,6 +84,58 @@ def test_committed_xacro_matches_generator(robot_dir):
         )
 
 
+def _biped_config():
+    """Return (config, limits) for lite_biped, the variant with an IMU and a four-bar."""
+    robot_dir = DESCRIPTIONS / "lite_biped"
+    cfg = json.loads((robot_dir / "cad" / "ros2_control.json").read_text())
+    root = robot_model.parse(robot_dir / "urdf" / "lite_biped.urdf").getroot()
+    return cfg, robot_model.joint_limits(root)
+
+
+@pytest.mark.skipif(not (DESCRIPTIONS / "lite_biped").is_dir(), reason="no lite_biped")
+def test_group_without_joints_is_rejected():
+    """A group with no joints would emit a bus block calling an undefined macro."""
+    cfg, limits = _biped_config()
+    cfg["groups"].append(
+        {"name": "neck", "block_name": "LiteBipedNeck", "can_interface_arg": "can_interface_left"})
+    with pytest.raises(ValueError, match="list no joints"):
+        urdf_to_xacro.build_ros2_control_xacro("lite_biped", cfg, limits)
+
+
+@pytest.mark.skipif(not (DESCRIPTIONS / "lite_biped").is_dir(), reason="no lite_biped")
+def test_linkage_without_use_linkage_arg_is_rejected():
+    """The four-bar macros reference ${use_linkage}, so the arg must be declared."""
+    cfg, limits = _biped_config()
+    del cfg["args"]["use_linkage"]
+    with pytest.raises(ValueError, match="use_linkage"):
+        urdf_to_xacro.build_ros2_control_xacro("lite_biped", cfg, limits)
+
+
+@pytest.mark.skipif(not (DESCRIPTIONS / "lite_biped").is_dir(), reason="no lite_biped")
+def test_partial_linkage_is_rejected():
+    """humanoid_devices_robstride aborts on some-but-not-all of the four bar lengths."""
+    cfg, limits = _biped_config()
+    for joint in cfg["joints"]:
+        if "linkage" in joint:
+            del joint["linkage"]["sign"]
+    with pytest.raises(ValueError, match="linkage is missing"):
+        urdf_to_xacro.build_ros2_control_xacro("lite_biped", cfg, limits)
+
+
+@pytest.mark.skipif(not (DESCRIPTIONS / "lite_biped").is_dir(), reason="no lite_biped")
+def test_imu_without_real_plugin_emits_no_sensor_component():
+    """A sim-only IMU is backed by MujocoSystem, so real hardware gets no sensor block."""
+    cfg, limits = _biped_config()
+    del cfg["imu"]["real_plugin"]
+    del cfg["imu"]["real_block_name"]
+    del cfg["args"]["imu_port"]
+    text = urdf_to_xacro.build_ros2_control_xacro("lite_biped", cfg, limits)
+    assert 'type="sensor"' not in text
+    assert "imu_port" not in text
+    # The combined block still carries the sim sensor.
+    assert f'<sensor name="{cfg["imu"]["name"]}">' in text
+
+
 @pytest.mark.skipif(not RC_DIRS, reason="no ros2_control robots")
 @pytest.mark.parametrize("robot_dir", RC_DIRS, ids=RC_IDS)
 def test_ros2_control_structure(robot_dir):
@@ -91,20 +143,54 @@ def test_ros2_control_structure(robot_dir):
     cfg = json.loads((robot_dir / "cad" / "ros2_control.json").read_text())
     text = (robot_dir / "xacro" / f"{robot}.ros2_control.xacro").read_text()
 
-    # one joint instantiation per configured joint
-    assert text.count(f"<xacro:{robot}_joint ") == len(cfg["joints"])
-    # all three backends present
+    # One joint instantiation per configured joint. A joint that declares a four-bar
+    # uses the linkage macro instead of the plain one.
+    plain = sum(1 for j in cfg["joints"] if not j.get("linkage"))
+    linkage = len(cfg["joints"]) - plain
+    assert text.count(f"<xacro:{robot}_joint ") == plain
+    assert text.count(f"<xacro:{robot}_linkage_joint ") == linkage
     for plugin in cfg["backends"].values():
         assert plugin in text, f"missing backend {plugin}"
-    # every non-stub group emits its bus block
     for group in cfg["groups"]:
-        if not group.get("stub"):
-            assert group["block_name"] in text
-    # CAN ids appear as joint-call attributes
+        assert group["block_name"] in text
     for joint in cfg["joints"]:
         assert f'can_id="{joint["can_id"]}"' in text
 
 
+@pytest.mark.skipif(not RC_DIRS, reason="no ros2_control robots")
+@pytest.mark.parametrize("robot_dir", RC_DIRS, ids=RC_IDS)
+def test_backend_args_follow_ros2_control_naming(robot_dir):
+    """The backend switches use the current ros2_control / Universal Robots names.
+
+    `use_fake_hardware` is the pre-Iron spelling, and a bare `use_sim` shadows the
+    unrelated `use_sim_time` node parameter. Both were renamed.
+    """
+    cfg = json.loads((robot_dir / "cad" / "ros2_control.json").read_text())
+    args = cfg["args"]
+    assert urdf_to_xacro.MOCK_ARG in args
+    assert urdf_to_xacro.SIM_ARG in args
+    assert "use_fake_hardware" not in args
+    assert "use_sim" not in args
+
+
+@pytest.mark.skipif(not RC_DIRS, reason="no ros2_control robots")
+@pytest.mark.parametrize("robot_dir", RC_DIRS, ids=RC_IDS)
+def test_joint_macros_are_backend_agnostic(robot_dir):
+    """No backend switch reaches a <joint>.
+
+    Every backend ignores the params it does not know -- MujocoSystem reads only `mimic`
+    and `multiplier`, and mock_components/GenericSystem stores the rest -- so the hardware
+    params are emitted unconditionally. The switches select a plugin and nothing else.
+    """
+    robot = robot_dir.name
+    text = (robot_dir / "xacro" / f"{robot}.ros2_control.xacro").read_text()
+    joint_macros = text.split("_ros2_control_combined")[0]
+    for arg in (urdf_to_xacro.MOCK_ARG, urdf_to_xacro.SIM_ARG):
+        assert arg not in joint_macros, f"{arg} leaked into the joint macros"
+    assert "xacro:unless" not in joint_macros
+    assert "xacro:if" not in joint_macros
+
+
 @pytest.mark.skipif(not RC_DIRS, reason="no ros2_control robots")
 @pytest.mark.parametrize("robot_dir", RC_DIRS, ids=RC_IDS)
 def test_ros2_control_limits_sourced_from_urdf(robot_dir):
diff --git a/tests/test_urdf_to_mjcf.py b/tests/test_urdf_to_mjcf.py
index e138cd2..b63dcf3 100644
--- a/tests/test_urdf_to_mjcf.py
+++ b/tests/test_urdf_to_mjcf.py
@@ -1,3 +1,4 @@
+"""Tests for the MJCF post-processing steps and the committed MJCF assets."""
 import xml.etree.ElementTree as ET
 from pathlib import Path
 
@@ -11,11 +12,9 @@
 MJCF_IDS = [p.parent.parent.name for p in MJCF_FILES]
 
 
-def test_replace_cylinders_with_capsules(tmp_path):
-    xml_path = tmp_path / "robot.xml"
-    xml_path.write_text(
-        """<?xml version="1.0"?>
-<mujoco>
+def test_replace_cylinders_with_capsules():
+    root = ET.fromstring(
+        """<mujoco>
   <worldbody>
     <body name="base">
       <geom name="upper_arm" type="cylinder" size="0.03 0.04" pos="1 2 3"/>
@@ -23,84 +22,93 @@ def test_replace_cylinders_with_capsules(tmp_path):
       <geom name="forearm" type="cylinder" size="0.02 0.05" quat="1 0 0 0"/>
     </body>
   </worldbody>
-</mujoco>
-""",
+</mujoco>""",
     )
 
-    count = replace_cylinders_with_capsules(xml_path)
+    count = replace_cylinders_with_capsules(root)
 
-    root = ET.parse(xml_path).getroot()
     geoms = {geom.get("name"): geom for geom in root.iter("geom")}
     assert count == 2
     assert geoms["upper_arm"].get("type") == "capsule"
+    # Retyping keeps every other attribute untouched.
     assert geoms["upper_arm"].get("size") == "0.03 0.04"
     assert geoms["upper_arm"].get("pos") == "1 2 3"
     assert geoms["foot"].get("type") == "box"
     assert geoms["forearm"].get("type") == "capsule"
 
 
-def test_replace_cylinders_with_capsules_returns_zero_when_no_cylinders(tmp_path):
-    xml_path = tmp_path / "robot.xml"
-    xml_path.write_text(
-        """<?xml version="1.0"?>
-<mujoco>
+def test_replace_cylinders_with_capsules_returns_zero_when_no_cylinders():
+    root = ET.fromstring(
+        """<mujoco>
   <worldbody>
     <body name="base">
       <geom name="foot" type="box" size="0.1 0.2 0.3"/>
     </body>
   </worldbody>
-</mujoco>
-""",
+</mujoco>""",
     )
 
-    assert replace_cylinders_with_capsules(xml_path) == 0
+    assert replace_cylinders_with_capsules(root) == 0
 
 
-@pytest.mark.skipif(not MJCF_FILES, reason="no generated MJCFs")
-@pytest.mark.parametrize("mjcf_path", MJCF_FILES, ids=MJCF_IDS)
-def test_committed_mjcf_loads_and_sensors_are_site_backed(mjcf_path):
-    """ros2_control safety guard: every committed MJCF must load, and every sensor
-    it carries must be attached to a <site>.
-
-    mujoco_ros2_control's plugin init loops over every sensor and builds
-    ``std::string(mj_id2name(model, mjOBJ_SITE, sensor_objid))``
-    (mujoco_ros2_control.cpp:124) -- null (SIGABRT) for a sensor whose object is not
-    a <site>. Fixed-base variants ship sensor-free; the floating-base biped ships
-    base-state sensors (framequat/gyro/accelerometer/velocimeter/framepos), all
-    attached to the same IMU <site>, so the one asset loads under both mjlab (reads
-    qpos/qvel from Entity data) and mujoco_ros2_control.
-    """
-    model = mujoco.MjModel.from_xml_path(str(mjcf_path))
-    for i in range(model.nsensor):
-        name = mujoco.mj_id2name(model, mujoco.mjtObj.mjOBJ_SENSOR, i)
-        assert model.sensor_objtype[i] == mujoco.mjtObj.mjOBJ_SITE, (
-            f"{mjcf_path} sensor {name!r} is not site-backed "
-            f"(objtype={model.sensor_objtype[i]}); mujoco_ros2_control would SIGABRT"
-        )
-
-
-def test_add_actuators_emits_position_actuators_and_no_sensors(tmp_path):
-    xml_path = tmp_path / "robot.xml"
-    xml_path.write_text(
-        """<?xml version="1.0"?>
-<mujoco>
+def test_add_actuators_emits_position_actuators_and_no_sensors():
+    root = ET.fromstring(
+        """<mujoco>
   <worldbody>
     <body name="base">
       <joint name="j1" actuatorfrcrange="-2 2"/>
       <geom name="g" type="box" size="0.1 0.1 0.1"/>
     </body>
   </worldbody>
-</mujoco>
-""",
+</mujoco>""",
     )
 
-    add_actuators(xml_path, {"j1": {"effort_limit": 5}})
+    add_actuators(root, {"j1": {"effort_limit": 5}})
 
-    root = ET.parse(xml_path).getroot()
     assert root.find("sensor") is None
     # <position>, not <motor>: the joint PD is evaluated every mj_step inside the
     # physics model rather than sampled once per controller_manager tick.
     actuators = root.findall("./actuator/position")
     assert root.findall("./actuator/motor") == []
     assert [a.get("name") for a in actuators] == ["j1"]
+    # forcerange is symmetric around zero, from the joint's effort_limit.
     assert actuators[0].get("forcerange") == "-5 5"
+
+
+def test_add_actuators_emits_no_ctrlrange():
+    """An RL policy may command past the joint limit to hold a saturating torque."""
+    root = ET.fromstring(
+        """<mujoco>
+  <worldbody>
+    <body name="base"><joint name="j1" actuatorfrcrange="-2 2" range="-1 1"/></body>
+  </worldbody>
+</mujoco>""",
+    )
+
+    add_actuators(root, {"j1": {"effort_limit": 5}})
+
+    actuator = root.find("./actuator/position")
+    assert actuator.get("ctrlrange") is None
+    assert actuator.get("ctrllimited") is None
+
+
+@pytest.mark.skipif(not MJCF_FILES, reason="no generated MJCFs")
+@pytest.mark.parametrize("mjcf_path", MJCF_FILES, ids=MJCF_IDS)
+def test_committed_mjcf_loads_and_sensors_are_site_backed(mjcf_path):
+    """Every committed MJCF must load, and every sensor it carries must sit on a <site>.
+
+    This guards ros2_control. mujoco_ros2_control's plugin init loops over every sensor
+    and builds ``std::string(mj_id2name(model, mjOBJ_SITE, sensor_objid))``
+    (mujoco_ros2_control.cpp:124), which is null and aborts for a sensor whose object is
+    not a <site>. Fixed-base variants ship sensor-free. The floating-base biped ships
+    base-state sensors (framequat, gyro, accelerometer, velocimeter, framepos) all
+    attached to the same IMU site, so the one asset loads under both mjlab, which reads
+    qpos/qvel from Entity data, and mujoco_ros2_control.
+    """
+    model = mujoco.MjModel.from_xml_path(str(mjcf_path))
+    for i in range(model.nsensor):
+        name = mujoco.mj_id2name(model, mujoco.mjtObj.mjOBJ_SENSOR, i)
+        assert model.sensor_objtype[i] == mujoco.mjtObj.mjOBJ_SITE, (
+            f"{mjcf_path} sensor {name!r} is not site-backed "
+            f"(objtype={model.sensor_objtype[i]}); mujoco_ros2_control would abort"
+        )
diff --git a/uv.lock b/uv.lock
index 82f8833..1276ea2 100644
--- a/uv.lock
+++ b/uv.lock
@@ -614,7 +614,7 @@ wheels = [
 
 [[package]]
 name = "robot-assets"
-version = "0.3.1"
+version = "0.4.0"
 source = { editable = "." }
 
 [package.optional-dependencies]