diff --git a/.devcontainer/README.md b/.devcontainer/README.md
new file mode 100644
index 0000000..304ad3e
--- /dev/null
+++ b/.devcontainer/README.md
@@ -0,0 +1,74 @@
+# DevContainer for Velxio
+
+This devcontainer provides a ready-to-use development environment for Velxio with:
+
+- Python 3.12 + FastAPI backend setup
+- Node.js 20 + React/Vite frontend setup
+- arduino-cli with AVR and RP2040 cores
+- Built wokwi-libs (avr8js, rp2040js, wokwi-elements)
+- Persistent volumes for node_modules and arduino cache
+
+## What's Included
+
+### Automatically Installed
+- **Arduino AVR** — Arduino Uno, Nano, Mega emulation
+- **RP2040** — Raspberry Pi Pico / Pico W emulation
+- **Frontend tooling** — TypeScript, ESLint, Tailwind CSS
+- **Backend tooling** — Python virtual environment with all dependencies
+
+### Not Included (Manual Setup)
+- **ESP32 Emulation (QEMU)** — Requires platform-specific compilation
+
+## Why ESP32 QEMU is Manual
+
+ESP32 emulation requires building QEMU from the lcgamboa fork, which:
+- Takes 15-30 minutes to compile
+- Requires platform-specific tools (MSYS2 on Windows, build-essential on Linux)
+- Generates 40-60 MB libraries excluded from git
+- Is optional — AVR and RP2040 work without it
+
+**For Docker users:** ESP32 emulation is pre-built and included in the official image.
+
+**For development:** If you need ESP32 emulation, see [docs/ESP32_EMULATION.md](../docs/ESP32_EMULATION.md)
+
+## Getting Started
+
+1. Open this repository in VS Code with the Dev Containers extension
+2. VS Code will automatically build and start the devcontainer
+3. Wait for `post-create.sh` to complete (~5-6 minutes)
+4. Start the backend: `cd backend && source venv/bin/activate && uvicorn app.main:app --reload --port 8001`
+5. Start the frontend: `cd frontend && npm run dev`
+6. Open http://localhost:5173
+
+## Optimization Notes
+
+- **Shallow clones** — wokwi-libs use `--depth=1` for faster setup (not recursive submodules)
+- **Parallel builds** — Backend, frontend, and wokwi-libs build concurrently
+- **Volume mounts** — node_modules and arduino cache persist between rebuilds
+- **User-local tools** — arduino-cli installs to `~/.local/bin` (no sudo required)
+
+## Ports Forwarded
+
+- **5173** — Frontend (Vite dev server)
+- **8001** — Backend (FastAPI)
+
+## Troubleshooting
+
+### Builds are slow
+First-time setup takes 5-6 minutes. Subsequent container starts use `post-start.sh` which only syncs dependencies (~30 seconds).
+
+### Permission errors on volumes
+The `post-create.sh` script fixes ownership automatically. If you still see errors, rebuild the container.
+
+### Arduino cores missing
+Check that arduino-cli is in PATH:
+```bash
+arduino-cli version
+arduino-cli core list  # should show arduino:avr and rp2040:rp2040
+```
+
+## Related Documentation
+
+- [Getting Started](../docs/getting-started.md) — Manual setup instructions
+- [ESP32 Emulation](../docs/ESP32_EMULATION.md) — Full ESP32 setup guide
+- [Architecture](../docs/ARCHITECTURE.md) — Project architecture overview
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index 5ca5597..2dc692b 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -26,7 +26,7 @@
   "postCreateCommand": "bash .devcontainer/post-create.sh",
   "postStartCommand": "bash .devcontainer/post-start.sh",
   "remoteEnv": {
-    "PATH": "${containerEnv:PATH}:${containerWorkspaceFolder}/frontend/node_modules/.bin:${containerWorkspaceFolder}/backend/venv/bin"
+    "PATH": "${containerEnv:PATH}:/home/vscode/.local/bin:${containerWorkspaceFolder}/frontend/node_modules/.bin:${containerWorkspaceFolder}/backend/venv/bin"
   },
   "forwardPorts": [5173, 8001],
   "portsAttributes": {
diff --git a/.devcontainer/post-create.sh b/.devcontainer/post-create.sh
index 35fbefa..cf44fe9 100755
--- a/.devcontainer/post-create.sh
+++ b/.devcontainer/post-create.sh
@@ -13,60 +13,89 @@ for d in frontend/node_modules wokwi-libs/avr8js/node_modules wokwi-libs/rp2040j
     sudo chown -R "$CURRENT_USER:$CURRENT_USER" "$d" 2>/dev/null || true
 done
 
-echo "==> Initializing git submodules..."
-# Nuke everything except node_modules (which are Docker volumes - can't delete)
-rm -rf wokwi-libs/avr8js/* wokwi-libs/rp2040js/* wokwi-libs/wokwi-elements/* wokwi-libs/wokwi-features/* wokwi-libs/wokwi-boards/* wokwi-libs/qemu-lcgamboa/*
-git submodule update --init --recursive
+echo "==> Cloning wokwi-libs (shallow, faster than submodules)..."
+# Only clone the 3 libs we actually use (avr8js, rp2040js, wokwi-elements)
+# Shallow clone with --depth=1 is much faster than recursive submodule init
+for lib in avr8js rp2040js wokwi-elements; do
+    if [ ! -d "wokwi-libs/$lib/.git" ]; then
+        rm -rf "wokwi-libs/$lib"
+        git clone --depth=1 "https://github.com/wokwi/$lib.git" "wokwi-libs/$lib"
+    else
+        echo "  -> wokwi-libs/$lib already exists, skipping clone"
+    fi
+done
 
-echo "==> Installing arduino-cli..."
+echo "==> Installing arduino-cli (user-local)..."
 if ! command -v arduino-cli &> /dev/null; then
-    curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sudo BINDIR=/usr/local/bin sh
+    mkdir -p "$HOME/.local/bin"
+    curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | BINDIR="$HOME/.local/bin" sh
+    export PATH="$HOME/.local/bin:$PATH"
 fi
 
 echo "==> Installing Arduino cores (this may take a few minutes)..."
-sudo arduino-cli core update-index
-if ! sudo arduino-cli core list | grep -q "arduino:avr"; then
-    sudo arduino-cli core install arduino:avr
+arduino-cli core update-index
+if ! arduino-cli core list | grep -q "arduino:avr"; then
+    arduino-cli core install arduino:avr
 fi
 
 # Add RP2040 board manager (guard against duplicates)
-if ! sudo arduino-cli config get board_manager.additional_urls | grep -q "rp2040"; then
-    sudo arduino-cli config add board_manager.additional_urls https://github.com/earlephilhower/arduino-pico/releases/download/global/package_rp2040_index.json
+if ! arduino-cli config get board_manager.additional_urls | grep -q "rp2040"; then
+    arduino-cli config add board_manager.additional_urls https://github.com/earlephilhower/arduino-pico/releases/download/global/package_rp2040_index.json
 fi
-if ! sudo arduino-cli core list | grep -q "rp2040:rp2040"; then
-    sudo arduino-cli core install rp2040:rp2040
+if ! arduino-cli core list | grep -q "rp2040:rp2040"; then
+    arduino-cli core install rp2040:rp2040
 fi
 
+# Note: ESP32 emulation (QEMU lcgamboa) is NOT installed by this script.
+# It requires platform-specific builds (MSYS2 on Windows, 15-30 min compile time)
+# and generates 40-60 MB libraries that are excluded from git.
+# - Docker images include pre-built QEMU libs automatically
+# - Development without ESP32 emulation works fine (AVR/RP2040 only)
+# - For full ESP32 support, see: docs/ESP32_EMULATION.md
+# - Backend auto-detects and falls back to UART-only mode if libs are missing
+
 echo "==> Setting up Python virtual environment (base layer)..."
 (cd backend
 python3 -m venv venv
 ./venv/bin/pip install wheel setuptools
 ./venv/bin/pip install -r requirements.txt) &
+BACKEND_PID=$!
 
 echo "==> Installing frontend dependencies..."
 (cd frontend
 HUSKY=0 npm install) &
+FRONTEND_PID=$!
 
-echo "==> Building wokwi-libs..."
+echo "==> Building wokwi-libs in parallel (avr8js, rp2040js, wokwi-elements)..."
 # Local wokwi-libs are cloned from GitHub instead of using npm packages.
 # This allows us to modify the emulators and components for Velxio-specific behavior.
 # Build outputs go to dist/ directories and are resolved via Vite aliases.
 (cd wokwi-libs/avr8js
 HUSKY=0 npm install
 npm run build) &
+AVR_PID=$!
 
 (cd wokwi-libs/rp2040js
 HUSKY=0 npm install
 npm run build) &
+RP2040_PID=$!
 
 (cd wokwi-libs/wokwi-elements
 HUSKY=0 npm install
 npm run build) &
+ELEMENTS_PID=$!
 
-wait  # Wait for all background jobs to complete
+echo "  -> Waiting for all parallel builds to complete..."
+wait $BACKEND_PID && echo "  ✓ Backend deps installed"
+wait $FRONTEND_PID && echo "  ✓ Frontend deps installed"
+wait $AVR_PID && echo "  ✓ avr8js built"
+wait $RP2040_PID && echo "  ✓ rp2040js built"
+wait $ELEMENTS_PID && echo "  ✓ wokwi-elements built"
 
 echo "==> Dev environment ready!"
 echo ""
 echo "To start development:"
 echo "  Backend:  cd backend && source venv/bin/activate && uvicorn app.main:app --reload --port 8001"
 echo "  Frontend: cd frontend && npm run dev"
+echo ""
+echo "Note: AVR/RP2040 emulation is ready. For ESP32 emulation (QEMU), see docs/ESP32_EMULATION.md"
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..cc57287
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,19 @@
+.PHONY: help dev-backend dev-frontend install clean
+
+.DEFAULT_GOAL := help
+
+help: ## Show available commands
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-15s %s\n", $$1, $$2}'
+
+dev-backend: ## Start backend (port 8001)
+	@cd backend && . venv/bin/activate && uvicorn app.main:app --reload --host 0.0.0.0 --port 8001
+
+dev-frontend: ## Start frontend (port 5173)
+	@cd frontend && npm run dev
+
+install: ## Install dependencies
+	@cd backend && python3 -m venv venv && . venv/bin/activate && pip install -r requirements.txt
+	@cd frontend && npm install
+
+clean: ## Remove venv and node_modules
+	@rm -rf backend/venv frontend/node_modules
diff --git a/README.md b/README.md
index 6a93554..bff913c 100644
--- a/README.md
+++ b/README.md
@@ -292,6 +292,12 @@ docker compose -f docker-compose.prod.yml up -d
 git clone https://github.com/davidmonterocrespo24/velxio.git
 cd velxio
 
+# With Makefile (Linux/macOS)
+make install
+make dev-backend
+make dev-frontend
+
+# Or manually:
 # Backend
 cd backend
 python -m venv venv && source venv/bin/activate  # Windows: venv\Scripts\activate