Clarify Experiment override paths (#1127)

## Summary
Clarify local and OSMO override paths

## Detailed description
- Explain the local shared.* and runs.* override namespaces.
- Show that OSMO Experiment overrides require the experiment_cfg.*
prefix.
- Add shared override examples and warn against the misleading +shared.*
suggestion.

Signed-off-by: Clemens Volk <cvolk@nvidia.com>

Author: cvolkcvolk

docs/pages/concepts/concept_arena_experiments.rst

@@ -74,36 +74,6 @@ field. Arena uses this name in command-line overrides, output directories, and r
 Runs keep their YAML order and execute locally in that order.
 
 
-Reuse values with ``shared``
-----------------------------
-
-``shared`` removes repetition. Arena applies these values to every Run, then places each Run's
-own values on top. A Run only needs to declare what is different.
-
-Values are applied in this order, from lowest to highest priority:
-
-.. code-block:: text
-
-   typed configuration defaults
-                 ↓
-   shared values, including shared.* CLI overrides
-                 ↓
-   values written in an individual Run
-                 ↓
-   runs.<name>.* CLI overrides
-
-.. dropdown:: Configuration rules
-   :animate: fade-in
-
-   * The only top-level fields are ``shared`` and ``runs``.
-   * ``runs`` must contain at least one Run.
-   * A Run name starts with a letter or underscore. It can then contain letters, numbers,
-     underscores, or hyphens.
-   * An override can change a field on a Run declared in the YAML, but it cannot add another Run.
-   * A ``shared.*`` override must point to a field already present below ``shared``. The Hydra
-     operators ``+``, ``++``, and ``~`` are not supported for shared values.
-
-
 .. _sequential-batch-experiment-runner:
 
 One definition, two execution paths
@@ -125,22 +95,43 @@ One definition, two execution paths
       Turns every Run into an independently scheduled group. Runs can execute at the same time
       when resources are available. OSMO then collects their outputs into one combined result.
 
+The CLI override root depends on the execution path:
+
 .. tab-set::
 
    .. tab-item:: Run locally
 
+      The Experiment Runner receives the Experiment Definition directly.
+
+      * Use ``shared.<path>=<value>`` to change a shared value.
+      * Use ``runs.<name>.<path>=<value>`` to change one Run.
+
       .. code-block:: bash
 
          python isaaclab_arena/evaluation/experiment_runner.py \
-           --experiment_config path/to/experiment.yaml
+           --experiment_config path/to/experiment.yaml \
+           shared.rollout_limit.num_steps=100
 
    .. tab-item:: Preview an OSMO workflow
 
+      OSMO nests the Experiment below ``experiment_cfg``, so Experiment overrides need that prefix.
+
+      * Use ``experiment_cfg.shared.<path>=<value>`` to change a shared value.
+      * Use ``experiment_cfg.runs.<name>.<path>=<value>`` to change one Run.
+
       .. code-block:: bash
 
          python -m osmo.submit_arena_experiment \
            --experiment_cfg path/to/experiment.yaml \
-           --dry_run
+           --dry_run \
+           experiment_cfg.shared.rollout_limit.num_steps=100
+
+      If Hydra suggests ``+shared.<path>=<value>``, do not add ``+``. Use
+      ``experiment_cfg.shared.<path>=<value>`` instead.
+
+Both commands override the same ``shared.rollout_limit.num_steps`` field declared in the
+Experiment Definition. A value written inside an individual Run still takes priority over the
+shared override.
 
 For remote policies, configure the policy client inside its Run like any other policy. Start the
 policy server separately for local execution. OSMO can co-schedule a server for supported policy
@@ -152,6 +143,36 @@ For OSMO setup and submission options, see :doc:`Multi-node Evaluation
 <../example_workflows/multi_node_evaluation/multi_node_evaluation>`.
 
 
+Reuse values with ``shared``
+----------------------------
+
+``shared`` removes repetition. Arena applies these values to every Run, then places each Run's
+own values on top. A Run only needs to declare what is different.
+
+Values are applied in this order, from lowest to highest priority:
+
+.. code-block:: text
+
+   typed configuration defaults
+                 ↓
+   shared values, including shared.* CLI overrides
+                 ↓
+   values written in an individual Run
+                 ↓
+   runs.<name>.* CLI overrides
+
+.. dropdown:: Configuration rules
+   :animate: fade-in
+
+   * The only top-level fields are ``shared`` and ``runs``.
+   * ``runs`` must contain at least one Run.
+   * A Run name starts with a letter or underscore. It can then contain letters, numbers,
+     underscores, or hyphens.
+   * An override can change a field on a Run declared in the YAML, but it cannot add another Run.
+   * A shared override must point to a field already present below ``shared`` in the Experiment
+     YAML. The Hydra operators ``+``, ``++``, and ``~`` are not supported for shared values.
+
+
 Choosing a runner
 -----------------
 

docs/pages/example_workflows/multi_node_evaluation/multi_node_evaluation.rst

@@ -217,16 +217,31 @@ For our experiment, the sensitivity analysis report looks like this:
 Adjust the Experiment at submission time
 ----------------------------------------
 
-You can tweak a Run at submission time, without editing its YAML file.
-To view the available override-able values, use the ``--list_overrides`` flag.
+You can adjust an Experiment at submission time without editing its YAML file. OSMO nests the
+Experiment below ``experiment_cfg``, so Experiment override paths start with that prefix.
+
+To inspect the effective Run values and submission settings, use the ``--list_overrides`` flag.
+Shared values have already been expanded into the Runs in this output; inspect the Experiment YAML
+to see which paths are declared below ``shared``.
 
 .. code-block:: bash
 
    python osmo/submit_arena_experiment.py \
      --experiment_cfg isaaclab_arena_environments/robolab/experiment_configs/robolab_20_tasks_pi0_and_cosmos.yaml \
      --list_overrides
 
-For example, to shorten the banana in bowl ``pi0.5`` run to four episodes:
+For example, to shorten every Run to four episodes, override the value declared below ``shared``:
+
+.. code-block:: bash
+
+   python osmo/submit_arena_experiment.py \
+     --experiment_cfg isaaclab_arena_environments/robolab/experiment_configs/robolab_20_tasks_pi0_and_cosmos.yaml \
+     experiment_cfg.shared.rollout_limit.num_episodes=4
+
+Do not add ``+`` to a shared override. If Hydra suggests ``+shared.<path>=<value>``, use the missing
+``experiment_cfg.`` prefix instead.
+
+To shorten only the banana in bowl ``pi0.5`` Run to four episodes:
 
 .. code-block:: bash
 

docs/pages/quickstart/arena_experiment.rst

@@ -98,8 +98,19 @@ records every Run, its status, and its episode results.
 Change values from the command line
 -----------------------------------
 
-You can adjust declared values without editing the YAML. This command reduces the number of
-parallel environments in the ``parallel_envs`` Run:
+You can adjust declared values without editing the YAML. This command changes the shared episode
+limit inherited by every Run:
+
+.. code-block:: bash
+
+   python isaaclab_arena/evaluation/experiment_runner.py \
+     --viz kit \
+     --experiment_config isaaclab_arena_environments/experiment_configs/getting_started_experiment.yaml \
+     shared.rollout_limit.num_episodes=4
+
+A value written directly inside a Run would still take priority over this shared override. To
+change only one Run, start the path with ``runs.<name>``. This command reduces the number of
+parallel environments in ``parallel_envs``:
 
 .. code-block:: bash
 
@@ -108,8 +119,9 @@ parallel environments in the ``parallel_envs`` Run:
      --experiment_config isaaclab_arena_environments/experiment_configs/getting_started_experiment.yaml \
      runs.parallel_envs.environment_builder.num_envs=8
 
-This changes only ``environment_builder.num_envs`` in the ``parallel_envs`` Run. All other values
-remain as written in the YAML.
+This changes only ``environment_builder.num_envs`` in the ``parallel_envs`` Run. OSMO uses the same
+paths below ``experiment_cfg``; for example, the shared override above becomes
+``experiment_cfg.shared.rollout_limit.num_episodes=4`` at submission time.
 
 See :doc:`Arena Experiments <../concepts/concept_arena_experiments>` for the full
 precedence order and configuration rules.

isaaclab_arena_environments/experiment_configs/getting_started_experiment.yaml

@@ -6,7 +6,9 @@
 # An Arena Experiment with shared values and four named Runs.
 # Values under shared are used by every Run below.
 # A Run only needs to list what is different; its values override the shared ones.
-# Use shared.<path>=<value> on the command line to change a shared value.
+# To change a shared value on the command line:
+# - with experiment_runner.py, use shared.<path>=<value>
+# - with osmo/submit_arena_experiment.py, use experiment_cfg.shared.<path>=<value>
 # A value written directly in a Run still takes priority.
 shared:
   environment: