container-superposition 0.1.6 → 0.1.8

package/overlays/comfyui/devcontainer.patch.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "runServices": ["comfyui"],
+    "forwardPorts": [8188],
+    "portsAttributes": {
+        "8188": {
+            "label": "ComfyUI",
+            "onAutoForward": "openBrowser"
+        }
+    },
+    "remoteEnv": {
+        "COMFYUI_URL": "http://comfyui:8188",
+        "COMFYUI_MODELS_DIR": "/opt/comfyui-models"
+    }
+}

package/overlays/comfyui/docker-compose.yml

@@ -0,0 +1,39 @@
+version: '3.8'
+
+services:
+    devcontainer:
+        volumes:
+            # Mount shared models root into devcontainer for direct filesystem access.
+            # When COMFYUI_MODELS_HOST_PATH is set this becomes a bind mount to that path;
+            # otherwise the named volume comfyui-models is used.
+            - ${COMFYUI_MODELS_HOST_PATH:-comfyui-models}:/opt/comfyui-models
+
+    comfyui:
+        image: ghcr.io/ai-dock/comfyui:${COMFYUI_VERSION:-latest-cuda}
+        restart: unless-stopped
+        volumes:
+            # Single root mount — ComfyUI discovers checkpoints/, loras/, etc. natively.
+            # Same source as the devcontainer mount above so both services share one copy.
+            - ${COMFYUI_MODELS_HOST_PATH:-comfyui-models}:/opt/ComfyUI/models
+            # Persist generated outputs (named volume by default, host path when COMFYUI_OUTPUT_PATH is set)
+            - ${COMFYUI_OUTPUT_PATH:-comfyui-output}:/opt/ComfyUI/output
+        environment:
+            - CLI_ARGS=${CLI_ARGS:---listen 0.0.0.0}
+        ports:
+            - '${COMFYUI_PORT:-8188}:8188'
+        deploy:
+            resources:
+                reservations:
+                    devices:
+                        - driver: nvidia
+                          count: all
+                          capabilities: [gpu]
+        networks:
+            - devnet
+
+volumes:
+    comfyui-models:
+    comfyui-output:
+
+networks:
+    devnet:

package/overlays/comfyui/overlay.yml

@@ -0,0 +1,20 @@
+id: comfyui
+name: ComfyUI
+description: Node-based image/video generation UI for Stable Diffusion and generative AI workflows
+category: dev
+supports:
+    - compose
+requires: []
+suggests:
+    - cuda
+    - python
+    - ollama
+conflicts: []
+tags:
+    - dev
+    - ai
+    - image-generation
+    - stable-diffusion
+    - comfyui
+ports:
+    - 8188

package/overlays/comfyui/setup.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# ComfyUI setup script — initializes the shared models directory
+
+set -e
+
+echo "🔧 Setting up ComfyUI..."
+
+# Pre-create all expected model subdirectories inside the shared models root.
+# Both the devcontainer and the ComfyUI sidecar mount this directory, so the
+# subdirectories must exist before ComfyUI starts (it does not create them).
+MODELS_DIR="${COMFYUI_MODELS_DIR:-/opt/comfyui-models}"
+
+echo "📁 Initializing model subdirectories at ${MODELS_DIR}..."
+
+# Ensure the root models directory exists and is writable by the current user.
+if ! mkdir -p "${MODELS_DIR}" 2>/dev/null; then
+    # Likely a permission issue on a mounted volume; try with sudo if available.
+    if command -v sudo >/dev/null 2>&1; then
+        echo "⚠️  ${MODELS_DIR} is not writable, attempting to create it with sudo..."
+        sudo mkdir -p "${MODELS_DIR}"
+        sudo chown "$(id -u):$(id -g)" "${MODELS_DIR}"
+    else
+        echo "❌ Failed to create ${MODELS_DIR} (permission denied and sudo not available)." >&2
+        exit 1
+    fi
+fi
+
+if [ ! -w "${MODELS_DIR}" ]; then
+    echo "❌ ${MODELS_DIR} is not writable by user $(id -un). Please adjust permissions and retry." >&2
+    exit 1
+fi
+
+for subdir in checkpoints loras controlnet clip_vision vae embeddings upscale_models; do
+    mkdir -p "${MODELS_DIR}/${subdir}"
+done
+echo "✓ ComfyUI model subdirectories initialized at ${MODELS_DIR}"

package/overlays/comfyui/verify.sh

@@ -0,0 +1,103 @@
+#!/bin/bash
+# Verification script for ComfyUI overlay
+# Confirms the shared models directory is set up correctly and the ComfyUI service is accessible
+
+set -e
+
+echo "🔍 Verifying ComfyUI overlay..."
+echo ""
+
+# Check shared models directory
+echo "1️⃣ Checking shared models directory..."
+MODELS_DIR="${COMFYUI_MODELS_DIR:-/opt/comfyui-models}"
+
+if [ ! -d "${MODELS_DIR}" ]; then
+    echo "   ❌ Models directory not found: ${MODELS_DIR}"
+    echo ""
+    echo "❌ ComfyUI overlay verification failed"
+    exit 1
+fi
+echo "   ✅ Models directory exists: ${MODELS_DIR}"
+
+if [ ! -w "${MODELS_DIR}" ]; then
+    echo "   ❌ Models directory is not writable: ${MODELS_DIR}"
+    echo ""
+    echo "❌ ComfyUI overlay verification failed"
+    exit 1
+fi
+echo "   ✅ Models directory is writable"
+
+EXPECTED_SUBDIRS=(checkpoints loras controlnet clip_vision vae embeddings upscale_models)
+MISSING_SUBDIRS=()
+for subdir in "${EXPECTED_SUBDIRS[@]}"; do
+    if [ ! -d "${MODELS_DIR}/${subdir}" ]; then
+        MISSING_SUBDIRS+=("${subdir}")
+    fi
+done
+
+if [ ${#MISSING_SUBDIRS[@]} -gt 0 ]; then
+    echo "   ❌ Missing model subdirectories: ${MISSING_SUBDIRS[*]}"
+    echo ""
+    echo "❌ ComfyUI overlay verification failed"
+    exit 1
+fi
+echo "   ✅ All expected model subdirectories present"
+
+# Check if curl is available
+echo ""
+echo "2️⃣ Checking curl availability..."
+if ! command -v curl &> /dev/null; then
+    echo "   ❌ curl not found"
+    echo ""
+    echo "❌ ComfyUI overlay verification failed (curl is required but not installed)"
+    exit 1
+fi
+echo "   ✅ curl found"
+
+# Check ComfyUI web UI
+echo ""
+echo "3️⃣ Checking ComfyUI service..."
+COMFYUI_URL="${COMFYUI_URL:-http://comfyui:8188}"
+COMFYUI_READY=false
+
+set +e
+for i in {1..30}; do
+    if curl -sf "${COMFYUI_URL}/" &> /dev/null; then
+        echo "   ✅ ComfyUI service is ready"
+        COMFYUI_READY=true
+        break
+    fi
+    sleep 2
+done
+set -e
+
+if [ "$COMFYUI_READY" = false ]; then
+    echo "   ❌ ComfyUI service not ready after 60 seconds"
+    echo ""
+    echo "   Tip: ComfyUI may take a while to start on first launch while it loads models."
+    echo "   Check logs with: docker compose logs comfyui"
+    echo ""
+    echo "❌ ComfyUI overlay verification failed"
+    exit 1
+fi
+
+# Check system stats endpoint
+echo ""
+echo "4️⃣ Checking ComfyUI system stats..."
+set +e
+STATS_JSON=$(curl -sf "${COMFYUI_URL}/system_stats")
+CURL_STATUS=$?
+set -e
+
+if [ $CURL_STATUS -eq 0 ] && [ -n "$STATS_JSON" ]; then
+    echo "   ✅ ComfyUI API is responding"
+else
+    echo "   ⚠️  Could not reach /system_stats endpoint (service may still be loading)"
+fi
+
+echo ""
+echo "✅ ComfyUI overlay verification complete"
+echo "   Models directory: ${MODELS_DIR}"
+echo "   Web UI: ${COMFYUI_URL}"
+echo "   API (example): ${COMFYUI_URL}/system_stats"
+echo "   Docs: https://github.com/comfyanonymous/ComfyUI"

package/overlays/commitlint/setup.sh

@@ -3,6 +3,11 @@
 
 set -e
 
+# Source shared setup utilities (provides load_nvm)
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+load_nvm
+
 echo "📝 Setting up commitlint..."
 
 # Install commitlint and conventional commits config globally

package/overlays/cuda/README.md

@@ -0,0 +1,179 @@
+# CUDA (NVIDIA GPU) Overlay
+
+Enables NVIDIA GPU passthrough for containerized ML, inference, and CUDA compute workloads.
+
+## Features
+
+- **GPU passthrough** - `--gpus=all` added to container `runArgs` so all host GPUs are available
+- **VS Code devcontainer GPU hint** - `hostRequirements.gpu = true` signals that a GPU is needed
+- **Setup check** - `setup.sh` verifies `nvidia-smi` on container start and prints actionable guidance when GPU access is unavailable
+- **Doctor integration** - `verify.sh` asserts `nvidia-smi` exits 0 for `container-superposition doctor` checks
+
+## Prerequisites (host-side — out of scope for this overlay)
+
+This overlay configures the _container_ side of GPU passthrough. The host must be prepared independently:
+
+1. **Supported NVIDIA GPU** — Pascal (GTX 10xx) or newer recommended
+2. **NVIDIA drivers** — Install the appropriate driver for your OS from [https://www.nvidia.com/drivers](https://www.nvidia.com/drivers)
+3. **NVIDIA Container Toolkit** — Install and configure following the [official guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html):
+    ```bash
+    # Example for Ubuntu
+    curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
+    curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
+      sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
+      sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
+    sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
+    ```
+4. **Configure the Docker runtime** — Run once after installing the toolkit:
+    ```bash
+    sudo nvidia-ctk runtime configure --runtime=docker
+    sudo systemctl restart docker
+    ```
+
+> ⚠️ **This overlay cannot install or replace host drivers.** Version alignment between the CUDA user-space libraries inside the container and the host kernel module is the user's responsibility.
+
+## How It Works
+
+The overlay patches `devcontainer.json` with two settings:
+
+```json
+{
+    "runArgs": ["--gpus=all"],
+    "hostRequirements": {
+        "gpu": true
+    }
+}
+```
+
+- **`runArgs: ["--gpus=all"]`** — Passes all host GPUs into the container via the NVIDIA Container Runtime.
+- **`hostRequirements.gpu: true`** — Tells VS Code that the host must have a GPU. VS Code will warn the user when opening the repo if no GPU is detected.
+
+The container image itself does **not** need to be an official NVIDIA CUDA image for the passthrough to work; however, CUDA libraries (e.g., `libcuda.so`) must exist inside the image to use CUDA APIs. See [Base Image](#base-image) below.
+
+## Base Image
+
+For GPU workloads you typically want a CUDA-capable base image. Popular choices:
+
+| Image                                     | Use case                    |
+| ----------------------------------------- | --------------------------- |
+| `nvidia/cuda:12.x.x-runtime-ubuntu22.04`  | Runtime-only (inference)    |
+| `nvidia/cuda:12.x.x-devel-ubuntu22.04`    | Full toolkit (compilation)  |
+| `nvcr.io/nvidia/pytorch:24.xx-py3`        | PyTorch + CUDA pre-built    |
+| `nvcr.io/nvidia/tensorflow:24.xx-tf2-py3` | TensorFlow + CUDA pre-built |
+
+Browse all tags at [hub.docker.com/r/nvidia/cuda](https://hub.docker.com/r/nvidia/cuda) and [catalog.ngc.nvidia.com](https://catalog.ngc.nvidia.com).
+
+To use a CUDA image, set the `image` field in your `.devcontainer/devcontainer.json` (for plain stack) or configure the appropriate service's `image` (or its `build`/`dockerfile`) in your compose-based devcontainer setup (for compose stack).
+
+## Common Commands
+
+### Check GPU availability
+
+```bash
+# List GPUs and driver version
+nvidia-smi
+
+# Compact GPU list
+nvidia-smi -L
+
+# Watch GPU utilisation (refreshes every second)
+nvidia-smi dmon -s u
+```
+
+### Query CUDA version
+
+```bash
+# CUDA runtime version (requires libcuda / nvidia-smi)
+nvidia-smi | grep "CUDA Version"
+
+# CUDA toolkit version (if nvcc is installed in the image)
+nvcc --version
+```
+
+### Python / PyTorch smoke test
+
+```python
+import torch
+print(torch.cuda.is_available())        # True
+print(torch.cuda.get_device_name(0))    # e.g. "NVIDIA GeForce RTX 4090"
+```
+
+### TensorFlow smoke test
+
+```python
+import tensorflow as tf
+print(tf.config.list_physical_devices('GPU'))
+```
+
+## Use Cases
+
+- **Model inference** — Run LLM or CV model inference with GPU acceleration
+- **Training** — Train deep learning models without leaving the dev container
+- **CUDA compute** — General-purpose GPU programming with CUDA C/C++ or PyCUDA
+- **Jupyter notebooks** — GPU-accelerated data science with Jupyter (combine with the `jupyter` overlay)
+- **CI parity** — Reproduce GPU CI failures locally inside the same container image
+
+**Integrates well with:**
+
+- `python` — Python runtime for ML workloads
+- `jupyter` — Interactive GPU notebooks
+
+## Troubleshooting
+
+### `nvidia-smi: command not found`
+
+The container cannot see the GPU. Work through this checklist:
+
+1. Verify host drivers: `nvidia-smi` should work on the _host_ before it works inside the container.
+2. Verify NVIDIA Container Toolkit is installed: `nvidia-ctk --version`.
+3. Verify Docker is configured to use the NVIDIA runtime:
+    ```bash
+    docker info | grep -i runtime
+    # Should list: nvidia
+    ```
+4. Rebuild the dev container after configuring the toolkit.
+
+### `Failed to initialize NVML: Driver/library version mismatch`
+
+The CUDA user-space library version inside the image does not match the host kernel module. Solutions:
+
+- Use a container image whose CUDA version matches (or is older than) the driver's supported CUDA version (`nvidia-smi` shows the maximum supported CUDA version on the host).
+- Update the host NVIDIA driver.
+
+### `--gpus` flag not recognised by Docker
+
+Your Docker version is older than 19.03 or the NVIDIA runtime is not configured as the default. Run:
+
+```bash
+sudo nvidia-ctk runtime configure --runtime=docker
+sudo systemctl restart docker
+```
+
+Or pass the runtime explicitly (not needed if the overlay's `runArgs` is picked up):
+
+```bash
+docker run --runtime=nvidia --gpus all nvidia/cuda:12.0-base nvidia-smi
+```
+
+### GPU not visible in GitHub Codespaces / cloud dev environments
+
+Cloud hosted dev environments (GitHub Codespaces, Gitpod) typically do not provide GPU pass-through. Use a GPU-enabled cloud VM (AWS p-instances, GCP A100, Azure NCv3) and run VS Code Remote SSH or a self-hosted Codespace runner with GPU support.
+
+## Security Considerations
+
+`--gpus=all` grants the container access to all host GPUs. This is appropriate for development but should not be used in untrusted or multi-tenant environments without additional isolation.
+
+## References
+
+- [NVIDIA Container Toolkit — install guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)
+- [NVIDIA CUDA Docker images](https://hub.docker.com/r/nvidia/cuda)
+- [NVIDIA NGC catalogue](https://catalog.ngc.nvidia.com)
+- [devcontainer spec — hostRequirements](https://containers.dev/implementors/json_reference/#general-properties)
+
+**Related Overlays:**
+
+- `python` — Python runtime for ML workloads
+- `jupyter` — GPU-accelerated interactive notebooks
+- `docker-in-docker` / `docker-sock` — Build GPU-enabled container images from within the dev container
+
+> 🔜 **ROCm (AMD GPU)** support is tracked in a separate overlay (`rocm`). When that overlay is added it must declare `cuda` in its `conflicts` to satisfy the bidirectional conflict requirement.

package/overlays/cuda/devcontainer.patch.json

@@ -0,0 +1,7 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "runArgs": ["--gpus=all"],
+    "hostRequirements": {
+        "gpu": true
+    }
+}

package/overlays/cuda/overlay.yml

@@ -0,0 +1,17 @@
+id: cuda
+name: CUDA (NVIDIA GPU)
+description: NVIDIA CUDA libraries and GPU passthrough for containerized ML/inference workloads
+category: dev
+supports: []
+requires: []
+suggests: []
+conflicts:
+    - rocm
+tags:
+    - dev
+    - gpu
+    - cuda
+    - nvidia
+    - ml
+    - inference
+ports: []

package/overlays/cuda/setup.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# CUDA overlay setup script
+# Checks that nvidia-smi is reachable inside the container and prints
+# a helpful message when the host is not configured for GPU passthrough.
+
+set -e
+
+echo "🖥️  Setting up CUDA (NVIDIA GPU) overlay..."
+
+if nvidia-smi -L >/dev/null 2>&1; then
+    echo "✓ nvidia-smi found: $(nvidia-smi --query-gpu=name --format=csv,noheader 2>/dev/null | head -n1 || nvidia-smi -L 2>/dev/null | head -n1 || echo 'GPU detected')"
+    echo "✓ CUDA overlay is ready"
+else
+    echo ""
+    echo "⚠️  nvidia-smi is installed but failed to run inside the container."
+    echo ""
+    echo "   GPU passthrough requires the following on the host:"
+    echo "   1. A supported NVIDIA GPU"
+    echo "   2. NVIDIA drivers installed on the host"
+    echo "   3. NVIDIA Container Toolkit installed and configured:"
+    echo "      https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html"
+    echo "   4. Docker configured to use the NVIDIA runtime:"
+    echo "      nvidia-ctk runtime configure --runtime=docker"
+    echo ""
+    echo "   This overlay adds '--gpus=all' to the container's runArgs and sets"
+    echo "   hostRequirements.gpu = true in devcontainer.json, but it cannot"
+    echo "   install or replace host drivers."
+    echo ""
+    echo "   Once the host is configured, rebuild the dev container."
+    echo ""
+    echo "ℹ️  CUDA overlay setup complete (nvidia-smi not functioning on this host)"
+fi

package/overlays/cuda/verify.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+# Verification script for CUDA overlay
+# Asserts nvidia-smi exits 0 (used by the doctor command)
+
+set -e
+
+echo "🔍 Verifying CUDA (NVIDIA GPU) overlay..."
+echo ""
+
+echo "1️⃣ Checking nvidia-smi..."
+if command -v nvidia-smi &> /dev/null; then
+    if nvidia-smi --query-gpu=name,driver_version,memory.total --format=csv,noheader 2>/dev/null; then
+        echo "   ✅ nvidia-smi is available and GPU is accessible"
+    elif nvidia-smi -L; then
+        echo "   ✅ nvidia-smi is available and GPU is accessible"
+    else
+        echo "   ❌ nvidia-smi is installed but failed to query GPU information"
+        echo ""
+        echo "   Possible causes:"
+        echo "   - NVIDIA driver is not loaded or mismatched with the container CUDA version"
+        echo "   - Insufficient permissions to access the GPU from this container"
+        echo "   - NVIDIA Container Toolkit / runtime is misconfigured"
+        echo ""
+        echo "   Resolve the above issues and retry the CUDA overlay verification."
+        exit 1
+    fi
+else
+    echo "   ❌ nvidia-smi not found"
+    echo ""
+    echo "   Ensure the host has:"
+    echo "   - NVIDIA drivers installed"
+    echo "   - NVIDIA Container Toolkit installed and configured"
+    echo "   - Docker runtime configured for NVIDIA (nvidia-ctk runtime configure)"
+    exit 1
+fi
+
+echo ""
+echo "✅ CUDA overlay verification complete"

package/overlays/devcontainer-cli/README.md

@@ -0,0 +1,50 @@
+# Dev Container CLI Overlay
+
+Installs the [official devcontainer CLI](https://github.com/devcontainers/cli) (`@devcontainers/cli`) for building, running, and testing devcontainer configurations from the command line.
+
+Useful for projects that generate or verify devcontainer configurations programmatically — including container-superposition itself.
+
+## Features
+
+- **`devcontainer` CLI** — Build, run, and test devcontainer configurations from the command line
+- **Node.js LTS** — Required runtime (included if not already present)
+- **VS Code Extension:** Dev Containers (ms-vscode-remote.remote-containers)
+
+## How It Works
+
+The setup script installs `@devcontainers/cli` as a global npm package. Node.js LTS is included via a devcontainer feature if not already available in the environment.
+
+## Common Commands
+
+```bash
+# Build a devcontainer image
+devcontainer build --workspace-folder .
+
+# Start a devcontainer
+devcontainer up --workspace-folder .
+
+# Run a command inside the devcontainer
+devcontainer exec --workspace-folder . -- bash -c "echo hello"
+
+# Check the CLI version
+devcontainer --version
+```
+
+## Use Cases
+
+- **CI/CD validation** — Build and test devcontainer configurations in pipelines
+- **Container-superposition development** — Verify generated `.devcontainer/` outputs actually build
+- **Toolchain testing** — Ensure devcontainer features and overlays compose correctly
+
+## Requires Docker
+
+The devcontainer CLI needs a Docker daemon to build containers. Pair with one of:
+
+- [`docker-sock`](../docker-sock/README.md) — bind-mount host Docker socket (simpler, works everywhere)
+- [`docker-in-docker`](../docker-in-docker/README.md) — isolated Docker daemon (better for nested containers)
+
+## References
+
+- [devcontainers/cli on GitHub](https://github.com/devcontainers/cli)
+- [Dev Containers specification](https://containers.dev/)
+- [devcontainer CLI npm package](https://www.npmjs.com/package/@devcontainers/cli)

package/overlays/devcontainer-cli/devcontainer.patch.json

@@ -0,0 +1,13 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "ghcr.io/devcontainers/features/node:1": {
+            "version": "lts"
+        }
+    },
+    "customizations": {
+        "vscode": {
+            "extensions": ["ms-vscode-remote.remote-containers"]
+        }
+    }
+}

package/overlays/devcontainer-cli/overlay.yml

@@ -0,0 +1,16 @@
+id: devcontainer-cli
+name: Dev Container CLI
+description: Official devcontainer CLI for building and testing devcontainer configurations
+category: dev
+supports: []
+requires: []
+suggests:
+    - docker-sock
+    - docker-in-docker
+conflicts: []
+tags:
+    - dev
+    - devcontainer
+    - cli
+    - testing
+ports: []

package/overlays/devcontainer-cli/setup.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+# Dev Container CLI setup script - Install @devcontainers/cli globally
+
+set -e
+
+# Source shared setup utilities (provides load_nvm)
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+load_nvm
+
+echo "📦 Installing @devcontainers/cli..."
+npm install -g @devcontainers/cli
+
+echo "✓ devcontainer CLI installed: $(devcontainer --version)"

package/overlays/direnv/devcontainer.patch.json

@@ -1,5 +1,11 @@
 {
     "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "direnv",
+            "apk": "direnv"
+        }
+    },
     "remoteEnv": {
         "DIRENV_LOG_FORMAT": ""
     }

package/overlays/direnv/setup.sh

@@ -5,15 +5,11 @@ set -e
 
 echo "🔐 Setting up direnv..."
 
-# Install direnv from package manager
-sudo apt-get update -qq
-sudo apt-get install -y direnv
-
-# Verify installation
+# Verify installation (installed via cross-distro-packages feature)
 if command -v direnv &> /dev/null; then
     echo "✓ direnv installed: $(direnv version)"
 else
-    echo "✗ direnv installation failed"
+    echo "✗ direnv not found — check cross-distro-packages feature"
     exit 1
 fi
 
@@ -80,6 +76,11 @@ EOF
     echo "✓ .envrc pre-allowed (run 'direnv deny' to disable)"
 fi
 
+# Ensure any pre-existing .envrc is also allowed (idempotent re-runs)
+if [ -f .envrc ]; then
+    direnv allow .envrc 2>/dev/null || true
+fi
+
 # Create sample .env file if it doesn't exist
 if [ ! -f .env ] && [ ! -f .env.example ]; then
     cat > .env.example << 'EOF'