feat: add admin startup scripts, update branding documentation

- add JUPYTERLAB_AUX_SCRIPTS_PATH env var for admin-managed startup
  scripts in user containers, default /mnt/shared/start-platform.d
- pass JUPYTERLAB_AUX_SCRIPTS_PATH to DockerSpawner.environment
- expand README Custom Branding from logo-only to full table covering
  logo, favicon, lab main icon, and lab splash icon
- add README Admin Startup Scripts section
- add User Environment category in settings_dictionary.yml
- add JUPYTERLAB_AUX_SCRIPTS_PATH to Dockerfile defaults

.claude/CLAUDE.md

@@ -77,6 +77,7 @@ This Python configuration file controls all JupyterHub behavior:
 - `JUPYTERHUB_FAVICON_URI`: Custom favicon - `file://` copies to static dir and enables CHP proxy routes for JupyterLab sessions (default: empty)
 - `JUPYTERHUB_LAB_MAIN_ICON_URI`: JupyterLab main icon - `file://` copies to static dir as `lab-main-icon{ext}`, URL passed to template (default: empty)
 - `JUPYTERHUB_LAB_SPLASH_ICON_URI`: JupyterLab splash icon - `file://` copies to static dir as `lab-splash-icon{ext}`, URL passed to template (default: empty)
+- `JUPYTERLAB_AUX_SCRIPTS_PATH`: Admin-managed startup scripts executed in user containers on launch, typically pointing to shared volume (default: empty)
 
 **GPU Auto-Detection**: When `JUPYTERHUB_GPU_ENABLED=2`, the platform attempts to run `nvidia-smi` in a CUDA container. If successful, GPU support is enabled for all spawned user containers via `device_requests`.
 

.claude/JOURNAL.md

@@ -286,5 +286,5 @@ This journal tracks substantive work on documents, diagrams, and documentation c
 94. **Task - Fix volume button positioning during React render**: Fixed button appearing on left side until page refresh<br>
     **Result**: MutationObserver fires while React is still rendering, causing volume button to be inserted before React finishes adding other buttons (server control buttons). Button ended up in middle of action cell instead of last. Fixed by repositioning existing button to end on each MutationObserver tick if `actionsCell.lastElementChild !== existingBtn` - ensures button stays at rightmost position regardless of when React renders additional buttons
 
-95. **Task - JupyterLab icon env vars and spawner env fix**: Added `JUPYTERHUB_LAB_MAIN_ICON_URI` and `JUPYTERHUB_LAB_SPLASH_ICON_URI` environment variables for JupyterLab main and splash icon customization, fixed spawner env var names to match lab image<br>
-    **Result**: Mirrors existing `JUPYTERHUB_FAVICON_URI` pattern for file copy - `file://` URIs copy source files to JupyterHub's static directory as `lab-main-icon{ext}` and `lab-splash-icon{ext}` (preserving original extension), then resolve to hub static URL path (`{base_url}hub/static/lab-main-icon{ext}`). External URLs passed through as-is. Unlike logo/favicon which are served by hub templates, lab icons are injected conditionally into `c.DockerSpawner.environment` as `JUPYTERLAB_MAIN_ICON_URI` and `JUPYTERLAB_SPLASH_ICON_URI` so JupyterLab extensions can reference them. Fixed critical spawner env var mismatch - hub was passing `JUPYTERHUB_SERVICE_MLFLOW`, `JUPYTERHUB_SERVICE_RESOURCES_MONITOR`, `JUPYTERHUB_SERVICE_TENSORBOARD` but lab startup scripts read `ENABLE_SERVICE_MLFLOW`, `ENABLE_SERVICE_RESOURCES_MONITOR`, `ENABLE_SERVICE_TENSORBOARD` (services were working only because Dockerfile defaults matched). Removed duplicate `JUPYTERHUB_GPU_ENABLED` from spawner env (already passed as `ENABLE_GPU_SUPPORT`). Updated six files: `config/jupyterhub_config.py` (icon copy logic, DockerSpawner.environment injection, spawner env var rename), `Dockerfile.jupyterhub` (ENV defaults), `compose.yml` (environment entries), `services/jupyterhub/conf/settings_dictionary.yml` (Branding section), `docs/custom-branding.md` (JupyterLab Icons section with resolution logic, container env var mapping, deployment example), `.claude/CLAUDE.md` (new env var documentation)
+95. **Task - JupyterLab icons, aux scripts, spawner env fix**: Added `JUPYTERHUB_LAB_MAIN_ICON_URI`, `JUPYTERHUB_LAB_SPLASH_ICON_URI`, and `JUPYTERLAB_AUX_SCRIPTS_PATH` environment variables, fixed spawner env var names to match lab image<br>
+    **Result**: Mirrors existing `JUPYTERHUB_FAVICON_URI` pattern for file copy - `file://` URIs copy source files to JupyterHub's static directory as `lab-main-icon{ext}` and `lab-splash-icon{ext}` (preserving original extension), then resolve to hub static URL path (`{base_url}hub/static/lab-main-icon{ext}`). External URLs passed through as-is. Unlike logo/favicon which are served by hub templates, lab icons are injected conditionally into `c.DockerSpawner.environment` as `JUPYTERLAB_MAIN_ICON_URI` and `JUPYTERLAB_SPLASH_ICON_URI` so JupyterLab extensions can reference them. Fixed critical spawner env var mismatch - hub was passing `JUPYTERHUB_SERVICE_MLFLOW`, `JUPYTERHUB_SERVICE_RESOURCES_MONITOR`, `JUPYTERHUB_SERVICE_TENSORBOARD` but lab startup scripts read `ENABLE_SERVICE_MLFLOW`, `ENABLE_SERVICE_RESOURCES_MONITOR`, `ENABLE_SERVICE_TENSORBOARD` (services were working only because Dockerfile defaults matched). Removed duplicate `JUPYTERHUB_GPU_ENABLED` from spawner env (already passed as `ENABLE_GPU_SUPPORT`). Added `JUPYTERLAB_AUX_SCRIPTS_PATH` for admin-managed startup scripts executed in user containers on launch - points to shared volume directory (`/mnt/shared/start-platform.d`) allowing admins to deploy scripts without image rebuilds. Updated README.md Custom Branding section from logo-only to full table of all four branding variables with deployment example and link to docs, added Admin Startup Scripts section documenting aux scripts path. Updated seven files: `config/jupyterhub_config.py` (icon copy logic, DockerSpawner.environment injection for icons and aux scripts, spawner env var rename), `Dockerfile.jupyterhub` (ENV defaults), `compose.yml` (environment entries), `services/jupyterhub/conf/settings_dictionary.yml` (Branding + User Environment sections), `docs/custom-branding.md` (JupyterLab Icons section), `README.md` (Custom Branding and Admin Startup Scripts sections), `.claude/CLAUDE.md` (new env var documentation)

README.md

@@ -414,18 +414,46 @@ services:
 
 #### Custom Branding
 
-Replace the default JupyterHub logo with a custom logo. Mount your logo file and set the path:
+Replace the default JupyterHub logo, favicon, and JupyterLab icons with custom assets. Mount files into the container and set `file://` URIs, or use external URLs directly.
+
+| Variable | Purpose |
+|----------|---------|
+| `JUPYTERHUB_LOGO_URI` | Hub login and navigation logo |
+| `JUPYTERHUB_FAVICON_URI` | Browser tab favicon for hub and JupyterLab sessions |
+| `JUPYTERHUB_LAB_MAIN_ICON_URI` | JupyterLab main toolbar logo |
+| `JUPYTERHUB_LAB_SPLASH_ICON_URI` | JupyterLab splash screen icon |
+
+Lab icons are resolved to hub static URLs and passed to spawned containers as `JUPYTERLAB_MAIN_ICON_URI` and `JUPYTERLAB_SPLASH_ICON_URI` environment variables for extensions to consume.
 
 ```yaml
 services:
   jupyterhub:
     environment:
       - JUPYTERHUB_LOGO_URI=file:///srv/jupyterhub/logo.svg
+      - JUPYTERHUB_FAVICON_URI=file:///srv/jupyterhub/favicon.ico
+      - JUPYTERHUB_LAB_MAIN_ICON_URI=file:///srv/jupyterhub/lab-icon.svg
+      - JUPYTERHUB_LAB_SPLASH_ICON_URI=file:///srv/jupyterhub/splash-icon.svg
     volumes:
-      - ./logo.svg:/srv/jupyterhub/logo.svg:ro
+      - ./branding/logo.svg:/srv/jupyterhub/logo.svg:ro
+      - ./branding/favicon.ico:/srv/jupyterhub/favicon.ico:ro
+      - ./branding/lab-icon.svg:/srv/jupyterhub/lab-icon.svg:ro
+      - ./branding/splash-icon.svg:/srv/jupyterhub/splash-icon.svg:ro
 ```
 
-Supported formats: SVG, PNG, JPG. The default path `/srv/jupyterhub/logo.svg` is used if file exists.
+See [docs/custom-branding.md](docs/custom-branding.md) for technical details on favicon CHP proxy routing and icon resolution.
+
+#### Admin Startup Scripts
+
+Run custom shell scripts in every user container at launch. Place scripts in a shared volume directory accessible to all containers. Scripts execute sequentially during container startup, before JupyterLab starts.
+
+```yaml
+services:
+  jupyterhub:
+    environment:
+      - JUPYTERLAB_AUX_SCRIPTS_PATH=/mnt/shared/start-platform.d
+```
+
+The default path `/mnt/shared/start-platform.d` resides on the shared volume, allowing admins to add, modify, or remove scripts without rebuilding images. Useful for installing additional packages, configuring environment variables, or setting up project-specific tooling across all user environments.
 
 #### Enable shared CIFS mount
 

compose.yml

@@ -85,6 +85,7 @@ services:
       # Misc
       - TF_CPP_MIN_LOG_LEVEL=3 # TensorFlow verbosity
       - CERTIFICATE_DOMAIN_NAME=localhost # self-signed certificate domain
+      - JUPYTERLAB_AUX_SCRIPTS_PATH=/mnt/shared/start-platform.d # admin-managed startup scripts for user environments
       - JUPYTERHUB_LOGO_URI= # custom logo URI (file:// or http(s)://)
       - JUPYTERHUB_FAVICON_URI= # custom favicon URI (file:// or http(s)://)
       - JUPYTERHUB_LAB_MAIN_ICON_URI= # JupyterLab main icon (file:// or URL)

config/jupyterhub_config.py

@@ -266,6 +266,7 @@ if c is not None:
          'ENABLE_GPU_SUPPORT': JUPYTERHUB_GPU_ENABLED,
          'ENABLE_GPUSTAT': JUPYTERHUB_GPU_ENABLED,
          'NVIDIA_DETECTED': NVIDIA_DETECTED,
+         'JUPYTERLAB_AUX_SCRIPTS_PATH': os.environ.get('JUPYTERLAB_AUX_SCRIPTS_PATH', ''),
     }
 
     # configure access to GPU if possible

services/jupyterhub/Dockerfile.jupyterhub

@@ -95,6 +95,8 @@ ENV JUPYTERHUB_ACTIVITYMON_INACTIVE_AFTER=60
 ENV JUPYTERHUB_ACTIVITYMON_TARGET_HOURS=8
 ENV JUPYTERHUB_ACTIVITYMON_RESOURCES_UPDATE_INTERVAL=10
 ENV JUPYTERHUB_ACTIVITYMON_VOLUMES_UPDATE_INTERVAL=3600
+# User environment customization
+ENV JUPYTERLAB_AUX_SCRIPTS_PATH=
 # Misc
 ENV TF_CPP_MIN_LOG_LEVEL=3
 ENV STELLARS_JUPYTERHUB_VERSION=${VERSION}

services/jupyterhub/conf/settings_dictionary.yml

@@ -109,6 +109,11 @@ Activity Monitor:
     description: Volume sizes refresh interval in seconds (background)
     default: "3600"
 
+User Environment:
+  - name: JUPYTERLAB_AUX_SCRIPTS_PATH
+    description: Admin-managed startup scripts executed in user containers on launch
+    default: ""
+
 Branding:
   - name: JUPYTERHUB_LOGO_URI
     description: Custom logo URI (file:// or URL)