Add Newton physics backend support

.agents/skills/add-robot/SKILL.md

@@ -17,7 +17,7 @@ Every robot config subclasses `RobotCfg` and overrides two hooks:
 
 - `_build_defaults(self, init_dict=None)` — read variant fields from `init_dict`,
   set them on `self`, then populate `urdf_cfg` / `control_parts` / `solver_cfg` /
-  `drive_pros` / `attrs`.
+  `joint_drive_props` / `attrs`.
 - `build_pk_serial_chain(self, device=...)` — return `{control_part: pk.SerialChain}`,
   reading the PK URDF from a single `_pk_urdf_path` source.
 
@@ -46,8 +46,8 @@ A cfg's `_build_defaults` must populate:
 - `urdf_cfg` (URDFCfg) or `fpath`
 - `control_parts` (Dict[str, List[str]]; joint names support regex)
 - `solver_cfg` (Dict[str, SolverCfg]; keys match `control_parts`)
-- `drive_pros` (JointDrivePropertiesCfg)
-- `attrs` (RigidBodyAttributesCfg)
+- `joint_drive_props` (JointDrivePropertiesCfg)
+- `attrs` (RigidBodyPhysicsCfg)
 
 `build_pk_serial_chain` must read from `_pk_urdf_path` (a property for
 constant-path robots, a method for variant-dependent paths). The PK chain's DOF
@@ -69,7 +69,7 @@ must match the matching `control_parts` entry (the test stub asserts this).
        self.urdf_cfg = URDFCfg(components=[...])
        self.control_parts = {"arm": ["JOINT[1-6]"]}
        self.solver_cfg = {"arm": OPWSolverCfg(end_link_name="link6", root_link_name="base_link")}
-       self.drive_pros = JointDrivePropertiesCfg(stiffness={"JOINT[1-6]": 1e4})
+       self.joint_drive_props = JointDrivePropertiesCfg(stiffness={"JOINT[1-6]": 1e4})
    ```
 
    Variant-aware template (reads version / arm_kind):
@@ -79,7 +79,7 @@ must match the matching `control_parts` entry (the test stub asserts this).
        init_dict = init_dict or {}
        self.version = MyRobotVersion(init_dict.get("version", "v1"))
        self.arm_kind = MyRobotArmKind(init_dict.get("arm_kind", "default"))
-       ...  # then urdf_cfg / control_parts / solver_cfg / drive_pros / attrs
+       ...  # then urdf_cfg / control_parts / solver_cfg / joint_drive_props / attrs
    ```
 
 4. **Implement `build_pk_serial_chain`** reading from `_pk_urdf_path`:
@@ -149,8 +149,8 @@ Do not copy those semantic declarations into the robot class.
 | `urdf_cfg` | URDFCfg | URDF file and components |
 | `control_parts` | Dict[str, List[str]] | Joint groups for control |
 | `solver_cfg` | Dict[str, SolverCfg] | IK solver configurations |
-| `drive_pros` | JointDrivePropertiesCfg | Joint stiffness, damping, force |
-| `attrs` | RigidBodyAttributesCfg | Rigid-body physics attributes |
+| `joint_drive_props` | JointDrivePropertiesCfg | Joint drive, limits, friction, and armature |
+| `attrs` | RigidBodyPhysicsCfg | Rigid-body physics attributes |
 | variant fields | enum / str / bool | Optional subclass fields |
 | `_pk_urdf_path` | property or method → str | URDF for the FK/IK serial chain |
 
@@ -160,5 +160,5 @@ Do not copy those semantic declarations into the robot class.
 - Registry: `embodichain/lab/sim/robots/__init__.py`
 - Docs: `docs/source/resources/robot/<name>.md`
 - Tests: `tests/sim/objects/test_robot_cfg.py`
-- Base class: `embodichain/lab/sim/cfg.py` (`RobotCfg`)
+- Base class: `embodichain/lab/sim/cfg/robot.py` (`RobotCfg`)
 - Guide: `docs/source/guides/add_robot.rst` · Tutorial: `docs/source/tutorial/add_robot.rst`

.agents/skills/add-solver/SKILL.md

@@ -219,7 +219,7 @@ exactly:
   `test_ur_solver.py`) to sample joint configs within limits with a safety
   margin.
 - A `BaseSolverTest` class with:
-  - `setup_simulation(self, sim_device)` — builds a `SimulationManagerCfg`,
+  - `setup_simulation(self, device)` — builds a `SimulationManagerCfg`,
     a `RobotCfg` whose `solver_cfg={"arm": <Name>SolverCfg(...)}` uses the new
     solver, and adds the robot via `self.sim.add_robot(cfg=cfg)`.
   - `test_ik(self)` — the round-trip contract:

.agents/skills/add-task-env/SKILL.md

@@ -86,6 +86,8 @@ For new task-first compositions, prefer:
 This is a component, not a runnable deployment. It owns:
 
 - `environment_id`;
+- exactly one explicit `physics: default|newton` backend and its optional,
+  backend-matching `physics_config`;
 - ordinary environment values such as episode limits and environment count;
 - physical simulation entities under `simulation`; and
 - manager configuration under `env`.
@@ -117,8 +119,10 @@ embodiment:
 
 The original inline Gym format remains supported. When extending an existing
 inline `env.json` or `env.yaml`, preserve that representation unless the user
-asked for component extraction. Never select a component and repeat its owned
-inline fields in the same deployment.
+asked for component extraction. Every inline runnable config declares exactly
+one `physics: default|newton` backend. Never select a component and repeat its
+owned inline fields, including `physics` or `physics_config`, in the same
+deployment. Use separate environment files for backend-specific settings.
 
 ### Optional Python entry point
 
@@ -173,6 +177,7 @@ trainer-routing smoke test when dependencies permit.
 - [ ] Task family, optional subdomain, task name, and runnable IDs are stable
 - [ ] Python and config paths share the same task-first hierarchy
 - [ ] Environment component and runnable deployment ownership are not mixed
+- [ ] Each environment file declares one backend and only matching physics fields
 - [ ] A Python task module exists only when the selected route needs it
 - [ ] No solution-method directory or same-named task package was introduced
 - [ ] Existing components and manager functors were reused where possible

.agents/skills/add-test/SKILL.md

@@ -83,7 +83,7 @@ from embodichain.lab.sim import SimulationManager, SimulationManagerCfg
 
 class TestMySimComponent:
     def setup_method(self):
-        config = SimulationManagerCfg(headless=True, sim_device="cpu")
+        config = SimulationManagerCfg(headless=True, device="cpu")
         self.sim = SimulationManager(config)
         # ... setup ...
 

.agents/skills/review-pr/SKILL.md

@@ -19,6 +19,10 @@ generic checklist or report an unproven concern as a finding.
 - **Architect** — Protect subsystem ownership, layering, dependency direction,
   public API and configuration contracts, extension boundaries, and viable
   evolution paths.
+- **Public API / developer experience engineer** — Review public import paths,
+  signatures, defaults, configuration schemas, CLI behavior, task discovery,
+  error messages, documentation examples, migration paths, and installed-wheel
+  usability from an external user's perspective.
 - **High-performance computing expert** — Identify reachable hot-path
   regressions in algorithmic complexity, batching/vectorization, allocation
   and memory layout, CPU/GPU transfers or synchronization, parallel or
@@ -36,6 +40,20 @@ generic checklist or report an unproven concern as a finding.
   semantic contracts, tool and action interfaces, planning/execution/
   verification loops, recovery and cancellation, observability, and safe
   autonomy.
+- **Security and trust-boundary engineer** — Inspect user-controlled
+  configuration and Task Programs, file paths, subprocesses, native or plugin
+  boundaries, credentials, package loading, and CI permissions for unsafe
+  execution, data exposure, privilege escalation, or fail-open behavior.
+
+### Role selection
+
+Select perspectives from the changed files and their contract neighbors; do
+not apply every role as a generic checklist. Read
+[references/reviewer-perspectives.md](references/reviewer-perspectives.md) when
+the change touches public APIs, untrusted inputs, long-running operations, or
+test and release boundaries. Keep the evidence standard unchanged: a role may
+raise a finding only when a reachable scenario, violated contract, and concrete
+impact are established.
 
 ## Review contract
 

.agents/skills/review-pr/references/reviewer-perspectives.md

@@ -0,0 +1,53 @@
+# Reviewer Perspectives
+
+Use this reference to select review lenses after the changed files and their
+contract neighbors are identified. It complements `review-matrix.md`: the
+matrix describes subsystem contracts, while this file describes the questions
+to ask from a user's or operator's point of view.
+
+## Perspective selection
+
+| Change signal | Select this perspective | Evidence to inspect |
+| --- | --- | --- |
+| Public Python modules, `__all__`, config classes, YAML/JSON schemas, CLI, task IDs, package data, examples, or migration behavior | Public API / developer experience | Public facades, strict loaders, callers, registration, docs checker, installed-package paths, and round-trip tests |
+| User-controlled files or programs, path resolution, dynamic imports, subprocesses, native extensions, plugins, secrets, or workflows | Security and trust boundary | Loader and validation boundaries, path joins, execution APIs, dependency loading, workflow permissions, and failure paths |
+| Reset/close/cancel, retries, checkpoint/resume, asynchronous workers, distributed execution, or long-running services | Reliability / operations (conditional lens) | Lifecycle owners, cleanup, idempotence, restart state, bounded queues, observability, and worker-failure handling |
+| Tests, fixtures, mocks, validation logic, or regression claims | Verification / test quality (mandatory pass, not a separate identity) | Test oracle, old-versus-new behavior, negative and boundary cases, partial batches, cleanup, determinism, and installation-level coverage |
+
+## Public API / developer experience
+
+Review the change as if consuming the installed package without repository
+knowledge. Confirm that:
+
+- public imports, `__all__`, signatures, defaults, typing, and lazy facades
+  agree with the documented API;
+- `configclass` objects, required fields, nested defaults, and serialized
+  configuration preserve their contract through construction and round trips;
+- CLI output, exit status, task discovery, relative paths, optional
+  dependencies, and package data work after wheel installation;
+- errors identify the invalid input at the owning boundary and do not leave a
+  partially initialized or misleading state;
+- breaking changes are intentional, documented, and accompanied by migration
+  or clear failure behavior.
+
+Do not report naming or prose preferences unless they make a supported workflow
+unreachable, ambiguous, or incompatible.
+
+## Security and trust boundary
+
+Trace data from untrusted configuration, Task Programs, file paths, workflow
+inputs, or optional extensions to the first side effect. Confirm strict
+decoding, safe path containment, least-privilege execution, secrets
+isolation, and fail-closed behavior. Treat unsafe deserialization, unchecked
+dynamic execution, path escape, dependency confusion, credential exposure, and
+workflow permission expansion as findings only when the changed code makes the
+scenario reachable and the impact concrete.
+
+## Conditional perspectives
+
+Reliability and verification are review lenses rather than mandatory reviewer
+identities. Use reliability for lifecycle and restart behavior that is not
+fully explained by the engine or agentic passes. Use verification for every
+test or validation change, checking that tests observe the contract and would
+fail on the relevant old behavior rather than merely mirroring the
+implementation.

.github/workflows/main.yml

@@ -12,27 +12,18 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/v') }}
 
+permissions:
+  contents: read
+  pull-requests: read
+
 jobs:
   lint:
-    runs-on: Linux
-    env:
-      NVIDIA_DRIVER_CAPABILITIES: all
-      NVIDIA_VISIBLE_DEVICES: all
-      NVIDIA_DISABLE_REQUIRE: 1
-    container: &container_template
-      image: 192.168.3.13:5000/dexsdk:ubuntu22.04-cuda12.8.0-h5ffmpeg-v3-py311
-      volumes:
-        - "/cache:/cache"
-        - "/usr/share/vulkan/icd.d:/usr/share/vulkan/icd.d"
-        - "/usr/share/vulkan/implicit_layer.d:/usr/share/vulkan/implicit_layer.d"
-        - "/usr/share/glvnd/egl_vendor.d:/usr/share/glvnd/egl_vendor.d"
-        - "/tmp/.X11-unix:/tmp/.X11-unix"
-        - "/dev/shm/shared:/dev/shm/shared"
-        - "/usr/share/nvidia:/usr/share/nvidia"
-      options: --memory 100g --gpus device=0 --shm-size 53687091200
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: ./.github/actions/activate-conda
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
       - name: Code Style check
         run: |
           echo "Workspace: ${GITHUB_WORKSPACE}"
@@ -47,28 +38,50 @@ jobs:
       - name: Public API docs check
         run: python docs/scripts/check_api_docs.py
 
+  docs-changes:
+    runs-on: ubuntu-latest
+    outputs:
+      required: ${{ steps.filter.outputs.docs }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
+        id: filter
+        with:
+          filters: |
+            docs:
+              - 'docs/**'
+              - 'embodichain/**'
+              - 'embodichain_tasks/**'
+              - 'examples/**'
+              - 'scripts/**'
+              - 'README.md'
+              - 'pyproject.toml'
+              - 'setup.py'
+              - 'VERSION'
+
   build:
-    if: ${{ !startsWith(github.ref, 'refs/tags/v') }}
-    needs: lint
+    if: ${{ !startsWith(github.ref, 'refs/tags/v') && needs.docs-changes.outputs.required == 'true' }}
+    needs: [lint, docs-changes]
     runs-on: Linux
     env:
       NVIDIA_DRIVER_CAPABILITIES: all
       NVIDIA_VISIBLE_DEVICES: all
       NVIDIA_DISABLE_REQUIRE: 1
-    container: *container_template
+    container: &container_template
+      image: 192.168.3.13:5000/dexsdk:ubuntu22.04-cuda12.8.0-h5ffmpeg-v3-py311
+      volumes:
+        - "/cache:/cache"
+        - "/usr/share/vulkan/icd.d:/usr/share/vulkan/icd.d"
+        - "/usr/share/vulkan/implicit_layer.d:/usr/share/vulkan/implicit_layer.d"
+        - "/usr/share/glvnd/egl_vendor.d:/usr/share/glvnd/egl_vendor.d"
+        - "/tmp/.X11-unix:/tmp/.X11-unix"
+        - "/dev/shm/shared:/dev/shm/shared"
+        - "/usr/share/nvidia:/usr/share/nvidia"
+      options: --memory 100g --gpus device=0 --shm-size 53687091200
     steps:
       - uses: actions/checkout@v4
       - uses: ./.github/actions/activate-conda
 
-      - name: Cache Python dependencies
-        id: cache-pip
-        uses: actions/cache@v4
-        with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-docs-${{ hashFiles('docs/requirements.txt') }}
-          restore-keys: |
-            ${{ runner.os }}-pip-docs-
-
       # Restore the full multi-version site from the last successful build.
       # The key never matches exactly (run_id is unique), so restore-keys is
       # always used to pick up the most recently saved full site.

AGENTS.md

@@ -65,6 +65,12 @@ omit the Python task module. Follow the authoritative
 [configuration and registration contract](agent_context/topics/env-framework/configuration.md)
 and `/add-task-env` before adding a deployment.
 
+Every inline runnable Gym config and reusable physical environment declares
+exactly one `physics: default|newton` backend. An environment component owns
+its optional matching `physics_config`; a deployment cannot repeat or override
+either field. Launcher `--physics` may confirm the file-owned backend but does
+not switch it. Use a separate environment config for each backend.
+
 ## Code and validation
 
 - Run **`black==26.3.1`**, using `black .`, before every commit.