Document QEMU emulation issues and multi-platform build considerations

- Add Multi-Platform Builds section to dockerfile-standards.mdc
- Document QEMU emulation failure symptoms and solutions
- Add testing guidelines for multi-platform builds in adding-new-images.mdc
- Add Platform Notes section to ESP-IDF README explaining amd64-only build
- Explain Rosetta 2 support for Mac M1/M2 users
- Document technical reasons for platform decision

Author: hacker-cb

.cursor/rules/adding-new-images.mdc

@@ -69,6 +69,26 @@ Before committing:
 - Test all README examples
 - Check image size is reasonable
 
+### Multi-Platform Build Testing
+
+When building for `linux/amd64,linux/arm64`:
+
+**Check for QEMU emulation issues:**
+1. Monitor build logs for both platforms
+2. Look for suspiciously fast completion times (~0.1s) on ARM64
+3. Verify that long-running commands (pip install) actually execute
+4. Test the published image on both platforms if possible
+
+**Signs of QEMU failure:**
+- ARM64 build step completes in 0.1s while AMD64 takes minutes
+- No error messages but packages aren't installed
+- Shell initialization scripts (source, export.sh) exit silently
+
+**Solutions if ARM64 fails:**
+1. Use direct venv paths instead of shell sourcing
+2. Use `python -m` for command verification
+3. Consider building AMD64 only (works via Rosetta 2 on Mac M1/M2)
+
 ### Testing Workflows with GitHub CLI
 
 Use `gh` CLI for remote workflow testing:

.cursor/rules/dockerfile-standards.mdc

@@ -36,3 +36,32 @@ alwaysApply: true
 - Optimize for automated builds
 - Keep images small - don't pre-download large toolchains unless necessary
 - Let frameworks download on first build (toolchains cache in volumes)
+
+### Multi-Platform Builds
+
+**QEMU Emulation Issues:**
+- ARM64 builds under QEMU emulation can fail silently
+- Scripts that source shell files (e.g., `source export.sh`) may exit immediately under QEMU
+- Commands complete in ~0.1s indicate QEMU emulation failure
+
+**Solutions:**
+1. **Use direct paths for installations:**
+   - Instead of: `bash -c '. ${IDF_PATH}/export.sh && pip install'`
+   - Use: `/path/to/venv/bin/pip install`
+   - This bypasses shell initialization that fails under QEMU
+
+2. **Use `python -m` for verification:**
+   - Instead of: `/path/to/venv/bin/pytest --version`
+   - Use: `python3 -m pytest --version`
+   - More portable and works across platforms
+
+3. **Consider amd64-only builds:**
+   - If ARM64 emulation issues persist, build `linux/amd64` only
+   - Docker Desktop on Mac M1/M2 runs amd64 via Rosetta 2 automatically
+   - ARM64 Linux users can use Docker's built-in emulation
+
+**Platform Configuration:**
+```dockerfile
+# In GitHub Actions workflow
+platforms: linux/amd64  # or linux/amd64,linux/arm64 if both work
+```

images/esp-idf/README.md

@@ -337,6 +337,25 @@ Available build arguments:
 - `QEMU_RELEASE_TAG` - GitHub release tag (default: `esp-develop-9.0.0-20240606`)
 - `QEMU_VERSION` - QEMU binary version string (default: `esp_develop_9.0.0_20240606`)
 
+### Platform Notes
+
+This image is built for **linux/amd64** only due to QEMU emulation issues with ARM64 builds during GitHub Actions multi-platform builds.
+
+**For Mac M1/M2 users:**
+- Docker Desktop automatically runs AMD64 images via Rosetta 2
+- Performance is excellent with transparent emulation
+- No action needed - just use the image normally
+
+**For ARM64 Linux users:**
+- Docker automatically emulates AMD64 when needed
+- Alternatively, build locally on ARM64 hardware (works perfectly)
+
+**Technical reason:**
+- ARM64 builds under QEMU emulation in GitHub Actions fail silently when executing shell initialization scripts
+- The `source ${IDF_PATH}/export.sh` command exits immediately under QEMU without error
+- Direct pip install paths work, but verification and testing require the activated environment
+- Building AMD64 only ensures consistent, reliable images for all users
+
 ## Version Information
 
 | Component | Version | Notes |