From c7cecbf7f2bdddfcb3b1ac4923c459f4b2ce9f1b Mon Sep 17 00:00:00 2001
From: yuecideng <dengyueci@qq.com>
Date: Thu, 29 Oct 2026 14:57:25 +0000
Subject: [PATCH] docs(sim): consolidate visualization and interaction guides

---
 .../sim-visualization/sim-visualization.md    |  2 +-
 docs/architecture/curated.json                |  2 +-
 ...{robot_redirect.html => doc_redirect.html} |  6 +++---
 docs/source/conf.py                           | 13 +++++++++----
 .../features/interaction/preview_asset.md     |  8 --------
 docs/source/guides/cli.md                     |  2 +-
 docs/source/guides/configuration.md           |  4 ++--
 docs/source/guides/preview_asset.md           |  2 +-
 docs/source/guides/run_task.md                |  2 +-
 docs/source/index.rst                         |  1 -
 docs/source/overview/sim/index.rst            |  6 +++---
 docs/source/overview/sim/sim_manager.md       |  8 ++++----
 .../sim/visualization}/gizmo.md               |  2 +-
 .../sim/visualization}/index.rst              | 19 ++++++++++++-------
 .../viser.md}                                 |  8 ++++----
 .../sim/visualization}/window.md              |  4 ++--
 docs/source/quick_start/install.md            |  4 ++--
 docs/source/tutorial/create_cloth.rst         |  2 +-
 docs/source/tutorial/create_scene.rst         |  4 ++--
 docs/source/tutorial/create_softbody.rst      |  2 +-
 docs/source/tutorial/gizmo.rst                |  2 +-
 docs/source/tutorial/rigid_object_group.rst   |  2 +-
 docs/source/tutorial/sensor.rst               |  2 +-
 23 files changed, 54 insertions(+), 53 deletions(-)
 rename docs/source/_templates/{robot_redirect.html => doc_redirect.html} (78%)
 delete mode 100644 docs/source/features/interaction/preview_asset.md
 rename docs/source/{features/interaction => overview/sim/visualization}/gizmo.md (98%)
 rename docs/source/{features/interaction => overview/sim/visualization}/index.rst (78%)
 rename docs/source/overview/sim/{viser_visualization.md => visualization/viser.md} (99%)
 rename docs/source/{features/interaction => overview/sim/visualization}/window.md (98%)

diff --git a/agent_context/topics/sim-visualization/sim-visualization.md b/agent_context/topics/sim-visualization/sim-visualization.md
index 17ef800b2..181d834a9 100644
--- a/agent_context/topics/sim-visualization/sim-visualization.md
+++ b/agent_context/topics/sim-visualization/sim-visualization.md
@@ -25,7 +25,7 @@
 | `embodichain/lab/scripts/_preview.py`, `preview_joint_control.py` | Shared preview stepping, frontend setup, and simulation-thread joint controls |
 
 Human-facing behavior and usage are documented in
-`docs/source/overview/sim/viser_visualization.md`.
+`docs/source/overview/sim/visualization/index.rst`.
 
 ## Ownership and Data Flow
 
diff --git a/docs/architecture/curated.json b/docs/architecture/curated.json
index 6a66ff16b..96d08e2d5 100644
--- a/docs/architecture/curated.json
+++ b/docs/architecture/curated.json
@@ -818,7 +818,7 @@
       ],
       "documentation": [
         {
-          "docname": "overview/sim/viser_visualization",
+          "docname": "overview/sim/visualization/viser",
           "label": "Browser visualization guide"
         }
       ],
diff --git a/docs/source/_templates/robot_redirect.html b/docs/source/_templates/doc_redirect.html
similarity index 78%
rename from docs/source/_templates/robot_redirect.html
rename to docs/source/_templates/doc_redirect.html
index 0ace13e92..4dd785f6e 100644
--- a/docs/source/_templates/robot_redirect.html
+++ b/docs/source/_templates/doc_redirect.html
@@ -1,9 +1,9 @@
-{% set target = pathto(robot_doc_redirects[pagename]) %}
+{% set target = pathto(doc_redirects[pagename]) %}
 <!doctype html>
 <html lang="en">
   <head>
     <meta charset="utf-8">
-    <title>Robot documentation moved</title>
+    <title>Documentation moved</title>
     <meta name="robots" content="noindex">
     <link rel="canonical" href="{{ target | e }}">
     <script>
@@ -14,6 +14,6 @@
     </noscript>
   </head>
   <body>
-    <p>This page has moved. <a href="{{ target | e }}">Continue to the robot documentation.</a></p>
+    <p>This page has moved. <a href="{{ target | e }}">Continue to the documentation.</a></p>
   </body>
 </html>
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 9c38c51b4..687d5a7cb 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -119,8 +119,13 @@
 # Use empty string to use relative paths from the build directory
 html_baseurl = ""
 
-# Keep published model URLs working after the vendor/model reorganization.
-robot_doc_redirects = {
+# Keep published URLs working after documentation reorganizations.
+doc_redirects = {
+    "features/interaction/index": "overview/sim/visualization/index",
+    "features/interaction/window": "overview/sim/visualization/window",
+    "features/interaction/gizmo": "overview/sim/visualization/gizmo",
+    "features/interaction/preview_asset": "guides/preview_asset",
+    "overview/sim/viser_visualization": "overview/sim/visualization/viser",
     "resources/robot/anymal_c": "resources/robot/anybotics/anymal_c",
     "resources/robot/microduck": "resources/robot/pollen_robotics/microduck",
     "resources/robot/unitree_g1": "resources/robot/unitree/g1",
@@ -138,7 +143,7 @@
     "resources/robot/aloha_mini": "resources/robot/alohamini/aloha_mini",
 }
 html_additional_pages = {
-    old_docname: "robot_redirect.html" for old_docname in robot_doc_redirects
+    old_docname: "doc_redirect.html" for old_docname in doc_redirects
 }
 
 # HTML context for better path handling
@@ -147,7 +152,7 @@
     "github_repo": "EmbodiChain",
     "github_version": "main",
     "doc_path": "docs/source",
-    "robot_doc_redirects": robot_doc_redirects,
+    "doc_redirects": doc_redirects,
 }
 
 html_theme_options = {
diff --git a/docs/source/features/interaction/preview_asset.md b/docs/source/features/interaction/preview_asset.md
deleted file mode 100644
index 8b8177f57..000000000
--- a/docs/source/features/interaction/preview_asset.md
+++ /dev/null
@@ -1,8 +0,0 @@
----
-orphan: true
----
-
-# Asset Preview Guide Moved
-
-Asset preview is a command-line workflow rather than an interaction frontend.
-Its documentation now lives in {doc}`Previewing Assets </guides/preview_asset>`.
diff --git a/docs/source/guides/cli.md b/docs/source/guides/cli.md
index c210501d8..b806feb23 100644
--- a/docs/source/guides/cli.md
+++ b/docs/source/guides/cli.md
@@ -268,7 +268,7 @@ embodichain run-task --gym_config config.yaml \
 The Viser panel supports environment visibility, camera-frustum selection, RGB
 preview, and overlay visibility. For supported object types, programmatic
 configuration, remote access, and performance details, see
-:doc:`../overview/sim/viser_visualization`.
+{doc}`../overview/sim/visualization/viser`.
 
 ### Preview Mode
 
diff --git a/docs/source/guides/configuration.md b/docs/source/guides/configuration.md
index 6ac6a2c50..dbfe9efae 100644
--- a/docs/source/guides/configuration.md
+++ b/docs/source/guides/configuration.md
@@ -326,7 +326,7 @@ uses this step-synchronized mode by default when neither the configuration nor
 
 Keep `viser_server.host` on loopback for remote workers and use SSH port
 forwarding unless the service is behind an authenticated gateway. See
-[Browser visualization with Viser](../overview/sim/viser_visualization.md) for
+[Browser visualization with Viser](../overview/sim/visualization/viser.md) for
 the full schema, supported scene content, and deformable-object behavior.
 
 ### Reusable Physical Environments and Runnable Deployments
@@ -563,6 +563,6 @@ This is automatically converted to a `SceneEntityCfg` object at runtime.
 
 - [Custom Functors Guide](custom_functors.md) — How to write observation, reward, event, and action functors
 - [Embodied Environments](../overview/gym/env.md) — Full environment configuration reference
-- [Browser Visualization](../overview/sim/viser_visualization.md) — Viser configuration and runtime behavior
+- [Browser Visualization](../overview/sim/visualization/viser.md) — Viser configuration and runtime behavior
 - [Tutorial: Modular Environment](../tutorial/modular_env.rst) — Complete example using config-driven setup
 - [Tutorial: RL Training](../tutorial/rl.rst) — RL training configuration walkthrough
diff --git a/docs/source/guides/preview_asset.md b/docs/source/guides/preview_asset.md
index a0fd2ef6f..54a1ebc33 100644
--- a/docs/source/guides/preview_asset.md
+++ b/docs/source/guides/preview_asset.md
@@ -84,7 +84,7 @@ embodichain preview-asset \
 
 Use `--viser-host`, `--viser-port`, `--viser-fps`, and the other standard
 `--viser-*` options to configure the browser server and update rates. See
-{doc}`Viser browser visualization </overview/sim/viser_visualization>` for the
+{doc}`Viser browser visualization </overview/sim/visualization/viser>` for the
 complete backend reference and remote-access guidance.
 
 ## Asset Type and Placement
diff --git a/docs/source/guides/run_task.md b/docs/source/guides/run_task.md
index d909cfdb9..4c25b9a98 100644
--- a/docs/source/guides/run_task.md
+++ b/docs/source/guides/run_task.md
@@ -210,7 +210,7 @@ created by `record_camera_data` under **Record cameras** from configured
 observation sensors under **Sensor cameras**.
 Limit the published batch with `--viser-env-ids`, and tune scene, image, or
 soft-body publication rates with the corresponding `--viser-*-fps` options. See
-{doc}`/overview/sim/viser_visualization` for browser controls and remote-access
+{doc}`/overview/sim/visualization/viser` for browser controls and remote-access
 details.
 
 ## Run and record
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 813d0c8a4..c74251f82 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -49,7 +49,6 @@ Table of Contents
    features/neural_dynamics.md
    features/generative_sim/index*
    features/workspace_analyzer/index*
-   features/interaction/index*
    features/toolkits/index*
 
 .. toctree::
diff --git a/docs/source/overview/sim/index.rst b/docs/source/overview/sim/index.rst
index 8ad157a1b..83e89d7e2 100644
--- a/docs/source/overview/sim/index.rst
+++ b/docs/source/overview/sim/index.rst
@@ -376,8 +376,8 @@ Choosing where to start
      - :doc:`sim_assets` and the object pages underneath it
    * - Add RGB, depth, stereo, segmentation, or contact observations
      - :doc:`sensors/index`
-   * - Inspect a headless or remote scene in a browser
-     - :doc:`viser_visualization`
+   * - Inspect or manipulate a scene through a native window or browser
+     - :doc:`visualization/index`
    * - Tune native rendering, DLSS, or frame timing
      - :doc:`sim_manager/rendering/index`
    * - Solve kinematics or generate a timed robot trajectory
@@ -416,6 +416,6 @@ See Also
    sim_manager.md
    sim_assets.md
    sensors/index
-   viser_visualization.md
+   visualization/index
    motion/index
    atomic_actions/index
diff --git a/docs/source/overview/sim/sim_manager.md b/docs/source/overview/sim/sim_manager.md
index 5fbf6aeee..e0451c3ce 100644
--- a/docs/source/overview/sim/sim_manager.md
+++ b/docs/source/overview/sim/sim_manager.md
@@ -178,7 +178,7 @@ The browser supports rigid objects and groups, robot and articulation links,
 cloth, soft bodies, camera frustums, low-frequency RGB preview, overlays, and a
 1 m ground grid. For configuration, performance behavior, deformable-object
 limitations, remote access, and troubleshooting, see
-{doc}`viser_visualization`.
+{doc}`visualization/viser`.
 
 ## Native point-cloud visualization
 
@@ -205,7 +205,7 @@ point_cloud = sim.visualize_point_cloud(
 
 The returned native point-cloud handle can be queried or modified with the
 DexSim point-cloud API. This method targets the native window; use the
-browser-overlay APIs documented in {doc}`viser_visualization` for Viser.
+browser-overlay APIs documented in {doc}`visualization/viser` for Viser.
 See {doc}`/tutorial/point_cloud_visualization` for a runnable color-and-position
 verification example.
 
@@ -314,5 +314,5 @@ For more methods and details, see the {doc}`SimulationManager API </api_referenc
 ### Related Documentation
 
 - {doc}`Basic scene creation </tutorial/create_scene>`
-- {doc}`Interactive Gizmos </features/interaction/gizmo>`
-- {doc}`Viser browser visualization <viser_visualization>`
+- {doc}`Interactive Gizmos </overview/sim/visualization/gizmo>`
+- {doc}`Viser browser visualization <visualization/viser>`
diff --git a/docs/source/features/interaction/gizmo.md b/docs/source/overview/sim/visualization/gizmo.md
similarity index 98%
rename from docs/source/features/interaction/gizmo.md
rename to docs/source/overview/sim/visualization/gizmo.md
index 4ba584e7c..4696fcc08 100644
--- a/docs/source/features/interaction/gizmo.md
+++ b/docs/source/overview/sim/visualization/gizmo.md
@@ -96,5 +96,5 @@ factory-created controller and does not create or update a duplicate.
 
 For the complete robot setup and IK walkthrough, continue with the
 {doc}`Gizmo tutorial </tutorial/gizmo>`. See
-{doc}`Viser browser visualization </overview/sim/viser_visualization>` for
+{doc}`Viser browser visualization <viser>` for
 server configuration and remote-access guidance.
diff --git a/docs/source/features/interaction/index.rst b/docs/source/overview/sim/visualization/index.rst
similarity index 78%
rename from docs/source/features/interaction/index.rst
rename to docs/source/overview/sim/visualization/index.rst
index 12f9656d4..61d7eb8b5 100644
--- a/docs/source/features/interaction/index.rst
+++ b/docs/source/overview/sim/visualization/index.rst
@@ -1,13 +1,17 @@
-Interactive Simulation
-======================
+.. _interactive-simulation:
 
-Interactive Simulation covers the frontends and controls used to inspect or
-manipulate a running simulation. Task-specific commands such as asset preview,
+Visualization and Interaction
+=============================
+
+This section covers the visualization frontends and controls used to inspect
+or manipulate a running simulation. Task-specific commands such as asset preview,
 workspace visualization, and grasp annotation remain in their own guides or
 feature sections.
 
-Interaction Frontends
----------------------
+.. _interaction-frontends:
+
+Visualization Frontends
+-----------------------
 
 .. list-table::
    :header-rows: 1
@@ -23,7 +27,7 @@ Interaction Frontends
    * - Viser browser
      - Headless or remote scene inspection, camera previews, environment
        visibility, overlays, and trusted browser controls.
-     - :doc:`Viser browser visualization </overview/sim/viser_visualization>`
+     - :doc:`Viser browser visualization <viser>`
 
 The native window and Viser are mutually exclusive visualization frontends.
 Both can expose the same registered Gizmo targets.
@@ -50,4 +54,5 @@ Related Workflows
    :maxdepth: 2
 
    Native window interaction <window.md>
+   Viser browser visualization <viser.md>
    Interactive Gizmos <gizmo.md>
diff --git a/docs/source/overview/sim/viser_visualization.md b/docs/source/overview/sim/visualization/viser.md
similarity index 99%
rename from docs/source/overview/sim/viser_visualization.md
rename to docs/source/overview/sim/visualization/viser.md
index 1b1a81225..54cdd7c11 100644
--- a/docs/source/overview/sim/viser_visualization.md
+++ b/docs/source/overview/sim/visualization/viser.md
@@ -314,10 +314,10 @@ Viser port behind an authenticated gateway.
 
 ## Related pages
 
-- {doc}`sim_manager`
-- {doc}`sim_assets`
-- {doc}`sensors/index`
-- {doc}`/features/interaction/gizmo`
+- {doc}`../sim_manager`
+- {doc}`../sim_assets`
+- {doc}`../sensors/index`
+- {doc}`gizmo`
 - {doc}`/guides/preview_asset`
 - {doc}`/tutorial/create_scene`
 - {doc}`/tutorial/sensor`
diff --git a/docs/source/features/interaction/window.md b/docs/source/overview/sim/visualization/window.md
similarity index 98%
rename from docs/source/features/interaction/window.md
rename to docs/source/overview/sim/visualization/window.md
index 53cd59576..d21158c9f 100644
--- a/docs/source/features/interaction/window.md
+++ b/docs/source/overview/sim/visualization/window.md
@@ -10,7 +10,7 @@ The native window and the Viser backend are mutually exclusive;
 native window while Viser is enabled.
 Likewise, `SimulationManager.start_visualization()` rejects Viser startup while
 the native window is open.
-See {doc}`Viser browser visualization </overview/sim/viser_visualization>` for
+See {doc}`Viser browser visualization <viser>` for
 the headless browser frontend.
 
 ## Default Window Controls
@@ -111,7 +111,7 @@ tutorial enables this option after preparing its initial joint pose.
 The entity gizmo is native-window only. The Viser backend offers an analogous
 **click-to-pick** flow (an *Enable click-to-pick Gizmo* checkbox instead of the
 **G** hotkey, since browsers do not expose keyboard events); see
-:doc:`tutorial/gizmo` for details.
+{doc}`Gizmo tutorial </tutorial/gizmo>` for details.
 
 ## Customizing Window Events
 
diff --git a/docs/source/quick_start/install.md b/docs/source/quick_start/install.md
index f3f45997b..0f72ac3c1 100644
--- a/docs/source/quick_start/install.md
+++ b/docs/source/quick_start/install.md
@@ -358,7 +358,7 @@ and forward the port:
 ssh -N -L 8080:127.0.0.1:8080 user@worker-host
 ```
 
-See [Browser visualization with Viser](../overview/sim/viser_visualization.md)
+See [Browser visualization with Viser](../overview/sim/visualization/viser.md)
 for supported objects, camera preview, update-rate options, and remote-access
 guidance.
 
@@ -380,5 +380,5 @@ Press `Ctrl+C` to stop; the script cleans up the simulation on exit.
 
 - [Quick Start Tutorial](../tutorial/index.rst)
 - [Simulation Manager](../overview/sim/sim_manager.md)
-- [Browser visualization with Viser](../overview/sim/viser_visualization.md)
+- [Browser visualization with Viser](../overview/sim/visualization/viser.md)
 - [Build documentation](docs.md)
diff --git a/docs/source/tutorial/create_cloth.rst b/docs/source/tutorial/create_cloth.rst
index a026eb050..b84f6dfa2 100644
--- a/docs/source/tutorial/create_cloth.rst
+++ b/docs/source/tutorial/create_cloth.rst
@@ -111,6 +111,6 @@ the source triangles, so its topology matches the simulated cloth surface.
 Deformable updates are sampled separately from rigid-body poses; adjust
 ``--viser-soft-body-fps`` to balance smoothness and browser/upload cost.
 
-See :doc:`/overview/sim/viser_visualization` for details.
+See :doc:`/overview/sim/visualization/viser` for details.
 
 Now that we have a basic understanding of how to create a cloth scene, let's move on to more advanced topics.
diff --git a/docs/source/tutorial/create_scene.rst b/docs/source/tutorial/create_scene.rst
index 3b3a599a2..b99acbed9 100644
--- a/docs/source/tutorial/create_scene.rst
+++ b/docs/source/tutorial/create_scene.rst
@@ -85,7 +85,7 @@ Use ``--viser-env-ids`` for selected parallel environments and
        --viser-env-ids 0 2 \
        --viser-fps 15
 
-See :doc:`/overview/sim/viser_visualization` for the complete object support
+See :doc:`/overview/sim/visualization/viser` for the complete object support
 matrix, server settings, telemetry, and remote-access guidance.
 
 Running the simulation
@@ -146,6 +146,6 @@ Next Steps
 - :doc:`create_softbody` — Add deformable bodies to your scene
 - :doc:`robot` — Load and control a robot
 - :doc:`sensor` — Add cameras and capture sensor data
-- :doc:`/overview/sim/viser_visualization` — Configure browser visualization
+- :doc:`/overview/sim/visualization/viser` — Configure browser visualization
 - :doc:`basic_env` — Create your first Gymnasium environment
 - :doc:`/overview/sim/sim_manager` — Full SimulationManager API reference
diff --git a/docs/source/tutorial/create_softbody.rst b/docs/source/tutorial/create_softbody.rst
index e7cdc4802..728ca43b7 100644
--- a/docs/source/tutorial/create_softbody.rst
+++ b/docs/source/tutorial/create_softbody.rst
@@ -78,6 +78,6 @@ render mesh are intentionally simplified. Lower
 ``--viser-soft-body-fps`` when publishing large soft bodies or several
 environments.
 
-See :doc:`/overview/sim/viser_visualization` for details.
+See :doc:`/overview/sim/visualization/viser` for details.
 
 Now that we have a basic understanding of how to create a soft-body scene, let's move on to more advanced topics.
diff --git a/docs/source/tutorial/gizmo.rst b/docs/source/tutorial/gizmo.rst
index e04cbbf2e..b0157795e 100644
--- a/docs/source/tutorial/gizmo.rst
+++ b/docs/source/tutorial/gizmo.rst
@@ -10,7 +10,7 @@ DexSim owns native entity and robot IK controllers; EmbodiChain keeps only the
 robot control-part adapter, Viser commands, and controller lifecycle management.
 
 For the cross-frontend capability summary, supported targets, lifecycle rules,
-and security boundary, see :doc:`/features/interaction/gizmo`.
+and security boundary, see :doc:`/overview/sim/visualization/gizmo`.
 
 The Code
 ~~~~~~~~
diff --git a/docs/source/tutorial/rigid_object_group.rst b/docs/source/tutorial/rigid_object_group.rst
index 0853b8879..bd296b107 100644
--- a/docs/source/tutorial/rigid_object_group.rst
+++ b/docs/source/tutorial/rigid_object_group.rst
@@ -59,5 +59,5 @@ Use ``--viser`` to publish every constituent object in the group to the browser:
 
 Each group member has its own pose and browser node. Shared geometry remains
 batched by the Viser backend. See
-:doc:`/overview/sim/viser_visualization` for server and environment-selection
+:doc:`/overview/sim/visualization/viser` for server and environment-selection
 options.
diff --git a/docs/source/tutorial/sensor.rst b/docs/source/tutorial/sensor.rst
index 983152822..e99be4963 100644
--- a/docs/source/tutorial/sensor.rst
+++ b/docs/source/tutorial/sensor.rst
@@ -123,6 +123,6 @@ After completing this tutorial, you can explore:
 - Using other sensor types (e.g., stereo cameras, force sensors)
 - Recording sensor data for offline analysis
 - Integrating sensor feedback into robot control or learning algorithms
-- Configuring :doc:`/overview/sim/viser_visualization` for remote camera inspection
+- Configuring :doc:`/overview/sim/visualization/viser` for remote camera inspection
 
 This tutorial provides a foundation for integrating perception into robotic simulation scenarios with SimulationManager.