XQuartz forwarding: env/compose cleanup + docs restructure

.devcontainer/devcontainer.json

@@ -1,14 +1,14 @@
 {
     "name": "simulations",
-    "dockerComposeFile": ["../docker/docker-compose.yml", "../docker/docker-compose-dev.yml"],
+    "dockerComposeFile": "../docker/docker-compose.yml",
     "service": "sim",
     "runServices": ["sim"],
 
     "workspaceFolder": "/home/trickfire/simulations",
     "remoteEnv": {
         "HOST_WORKSPACE": "${localWorkspaceFolder}"
     },
-    "initializeCommand": "bash .devcontainer/detect-host-env.sh || true",
+    "initializeCommand": "bash .devcontainer/host-env.sh || true",
     "postCreateCommand": "pip3 install --break-system-packages -e .", // install the sim cli
     "postStartCommand": "bash ./.devcontainer/x_server.sh || true",
 
@@ -19,34 +19,26 @@
                 "shfmt.executablePath": "/usr/local/bin/shfmt"
             },
             "extensions": [
-                // --- Python ---
                 "ms-python.python",
                 "ms-python.vscode-pylance",
                 "charliermarsh.ruff",
                 "ms-python.mypy-type-checker",
-
-                // --- C and C++ ---
                 "ms-vscode.cmake-tools",
                 "josetr.cmake-language-support-vscode",
                 "llvm-vs-code-extensions.vscode-clangd",
                 "ms-vscode.makefile-tools",
-
-                // --- Robotics / ROS / URDF / meshes ---
                 "Ranch-Hand-Robotics.rde-ros-2",
                 "smilerobotics.urdf",
                 "morningfrog.urdf-visualizer",
                 "misiekhardcore.stl-previewer",
-
-                // --- Container ---
                 "ms-azuretools.vscode-docker",
-
-                // --- Formatters ---
                 "esbenp.prettier-vscode",
                 "yzhang.markdown-all-in-one",
                 "DotJoshJohnson.xml",
                 "tamasfe.even-better-toml",
                 "github.vscode-github-actions",
-                "mkhl.shfmt"
+                "mkhl.shfmt",
+                "unifiedjs.vscode-mdx"
             ]
         }
     }

.devcontainer/detect-host-env.sh → .devcontainer/host-env.sh

@@ -3,13 +3,15 @@ set -eu
 
 script_dir="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
 docker_dir="$(cd "$script_dir/../docker" && pwd)"
-env_out="$docker_dir/.env"
-host_out="$docker_dir/.env.host"
+
 defaults="$docker_dir/.env.defaults"
 overrides="$docker_dir/.env.local"
+env_out="$docker_dir/.env"
 
 uname_s="$(uname -s 2>/dev/null || echo unknown)"
 
+log() { printf "\033[1;36m%s\033[0m\n" "$1"; }
+
 gpu_available() {
     [ "$uname_s" = "Linux" ] || return 1
     command -v nvidia-smi >/dev/null 2>&1 || return 1
@@ -18,24 +20,9 @@ gpu_available() {
 }
 
 gpu_runtime=""
-if gpu_available; then
-    gpu_runtime="nvidia"
-fi
-
-{
-    cat "$defaults"
-    if [ -f "$overrides" ]; then
-        echo ""
-        echo "# --- user overrides (docker/.env.local) ---"
-        cat "$overrides"
-    fi
-    echo ""
-    echo "# --- host-detected (generated, do not edit) ---"
-    echo "SIM_GPU_RUNTIME=$gpu_runtime"
-} >"$env_out"
+gpu_available && gpu_runtime="nvidia"
 
-{
-    echo "# generated by .devcontainer/detect-host-env.sh — do not edit or commit"
+write_display_env() {
     case "$uname_s" in
     Darwin)
         echo "# host: macOS (XQuartz over TCP + VirtualGL)"
@@ -54,16 +41,37 @@ fi
         echo "DISPLAY=${DISPLAY:-:0}"
         ;;
     *)
-        echo "# host: unknown ($uname_s) — falling back to local display :0"
+        echo "# host: unknown ($uname_s) - falling back to local display :0"
         echo "DISPLAY=${DISPLAY:-:0}"
         ;;
     esac
+}
+
+write_env() {
+    echo "# generated by .devcontainer/host-env.sh - do not edit or commit"
+    echo "# to change ports/flags, edit docker/.env.defaults (shared) or docker/.env.local (yours)"
+    echo ""
+
+    cat "$defaults"
+
+    if [ -f "$overrides" ]; then
+        echo ""
+        echo "# --- user overrides (docker/.env.local) ---"
+        cat "$overrides"
+    fi
+
+    echo ""
+    echo "# --- host-detected (generated, do not edit) ---"
+    write_display_env
+    echo "SIM_GPU_RUNTIME=$gpu_runtime"
+
     if [ -n "$gpu_runtime" ]; then
-        echo "# nvidia GPU detected (runtime: nvidia)"
         echo "NVIDIA_VISIBLE_DEVICES=all"
         echo "NVIDIA_DRIVER_CAPABILITIES=graphics,display,compute,utility"
         echo "__EGL_VENDOR_LIBRARY_FILENAMES=/usr/share/glvnd/egl_vendor.d/10_nvidia.json"
     fi
-} >"$host_out"
+}
+
+write_env >"$env_out"
 
-echo "[detect-host-env] host=$uname_s gpu=${gpu_runtime:-none} -> wrote docker/.env, docker/.env.host"
+echo "[INFO] host=$uname_s gpu=${gpu_runtime:-none}"

.devcontainer/x_server.sh

@@ -1,10 +1,6 @@
 #!/usr/bin/env bash
-
-# --------------------------------------------------------------------------------------------
-# Starts a headless X11 desktop (Xorg/Xvfb + Openbox + x11vnc + noVNC) inside the container.
-# Intended for running GUI apps (Gazebo) in Docker.
-# Supports --verbose flag for debugging (prints all output to console instead of log file).
-# --------------------------------------------------------------------------------------------
+# Sets up the container's display: Wayland/X11 passthrough when available, otherwise a
+# headless Xorg/Xvfb + Openbox + x11vnc + noVNC stack. See docs/reference/docker-environment.mdx.
 
 set -eo pipefail
 trap '' HUP
@@ -101,7 +97,7 @@ try_display_passthrough() {
     fi
 
     # Case 1: Linux host with a Wayland compositor, or WSL2 with WSLg. The host socket is
-    # bind-mounted into /run/host-runtime by docker-compose-dev.yml.
+    # bind-mounted into /run/host-runtime by docker-compose.yml.
     local wayland_sock="/run/host-runtime/${WAYLAND_DISPLAY:-wayland-0}"
     if [ -S "$wayland_sock" ]; then
         log "[X11] Using Wayland socket at $wayland_sock"

.gitignore

@@ -7,22 +7,19 @@
 !.vscode/launch.json
 !.vscode/extensions.json
 
-# pixi
-.pixi/
-
-# Python
+# python
 .mypy_cache
 __pycache__
 *.egg-info/
 build/
 **/.venv
 
-# ROS2
+# ros
 gazebo/install
 gazebo/build
 gazebo/log
 
-# sim create tests
+# sim tests
 cli/gazebo/create/tests
 
 # chrono outputs
@@ -31,14 +28,8 @@ chrono/results/*
 
 # env
 **/*.env
-# docker/.env is generated each `devcontainer up` by .devcontainer/detect-host-env.sh
-# (from docker/.env.defaults + docker/.env.local + host detection). docker/.env.defaults
-# is the committed source of truth; docker/.env.local holds per-machine overrides.
 docker/.env
-docker/.env.host
 docker/.env.local
 
 # trickfire-docs
-.trickfire-docs/
 dist/
-.cache/

.vscode/settings.json

@@ -29,6 +29,10 @@
         "editor.formatOnSave": true,
         "editor.formatOnPaste": true
     },
+    "[mdx]": {
+        "editor.wordWrap": "on",
+        "editor.defaultFormatter": "esbenp.prettier-vscode"
+    },
     "[json]": {
         "editor.defaultFormatter": "esbenp.prettier-vscode",
         "editor.formatOnSave": true,
@@ -74,6 +78,5 @@
         "${workspaceFolder}/gazebo/sim_common"
     ],
     "ROS2.distro": "jazzy",
-    "cmake.ignoreCMakeListsMissing": true,
-    "autoDevcontainer.enabled": true
+    "cmake.ignoreCMakeListsMissing": true
 }

README.md

@@ -6,8 +6,8 @@ Robot simulations for TrickFire Robotics - Gazebo Harmonic (ROS 2 Jazzy) for rob
 
 **Full documentation is at [docs.trickfirerobotics.com/simulations](https://docs.trickfirerobotics.com/simulations)**
 
-- [Getting Started](https://docs.trickfirerobotics.com/simulations/getting-started) - native setup, Dev Container alternative, first launch
+- [Getting Started](https://docs.trickfirerobotics.com/simulations) - native setup, Dev Container alternative, first launch
 - [Running Gazebo](https://docs.trickfirerobotics.com/simulations/gazebo/gazebo) - `sim gazebo` CLI usage and flags
 - [Running Chrono](https://docs.trickfirerobotics.com/simulations/chrono/chrono) - `sim chrono` CLI usage
 - [Adding a New Robot](https://docs.trickfirerobotics.com/simulations/gazebo/adding-robots) - OnShape to Gazebo with `sim gazebo create`
-- [Environment](https://docs.trickfirerobotics.com/simulations/reference/docker-environment) - Docker environment in depth
+- [Dev Notes](https://docs.trickfirerobotics.com/simulations/dev-notes) - architecture decisions, Docker environment internals, CLI tips

chrono/data/vsg/imgui.ini

@@ -8,6 +8,6 @@ Size=531,121
 
 [Window][Simulation]
 Pos=5,5
-Size=349,458
+Size=238,362
 Collapsed=1