From e313de31e37c643a492fc4844b56ba2ccc81af1e Mon Sep 17 00:00:00 2001
From: William Valentin <william.valentin.info@gmail.com>
Date: Sun, 14 Sep 2025 17:00:03 -0700
Subject: [PATCH] docs(readme): update Docker section with current status and
 workarounds

- Document Docker networking issues in main README
- Add host networking workaround instructions
- Update Docker command examples with current status
- Recommend native development as primary option
- Reference docker/README.md for detailed troubleshooting
- Update quick start section with networking alternatives
---
 README.md | 33 ++++++++++++++++++++++++++++-----
 1 file changed, 28 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index da035eb..5ab9faf 100644
--- a/README.md
+++ b/README.md
@@ -80,8 +80,11 @@ make server
 # Custom configuration
 ./start-server.sh --host 127.0.0.1 --port 3000 --log-level debug
 
-# Docker development
+# Docker development (if networking works)
 make docker-dev
+
+# Docker with host networking (workaround)
+make docker-dev-host
 ```
 
 Access the web interface at: **http://localhost:8000**
@@ -372,10 +375,10 @@ uv pip show <pkg>  # Show package info
 
 **Docker Development:**
 ```bash
-make docker-build  # Build all images
-make docker-dev    # Start dev environment
-make docker-test   # Run tests in container
-make docker-clean  # Clean up containers
+make docker-build       # Build images (may fail due to networking)
+make docker-dev         # Development environment
+make docker-dev-host    # Development with host networking (workaround)
+make docker-clean       # Clean up containers
 ```
 
 ### Code Style
@@ -387,6 +390,9 @@ make docker-clean  # Clean up containers
 
 ## 🐳 Docker Support
 
+⚠️ **Current Status**: Docker networking issues prevent standard container builds. Use native development instead.
+
+### Container Templates
 UnitForge includes templates for containerized services:
 
 ```bash
@@ -401,6 +407,23 @@ UnitForge includes templates for containerized services:
   --param image=registry.example.com/myapp:v1.0
 ```
 
+### Docker Commands (when networking is fixed)
+```bash
+make docker-build         # Build images
+make docker-dev           # Development environment
+make docker-prod          # Production environment
+make docker-dev-host      # Development with host networking (workaround)
+make docker-clean         # Clean up containers
+```
+
+**Recommended**: Use native development until Docker networking is resolved:
+```bash
+source .venv/bin/activate
+./start-server.sh
+```
+
+See `docker/README.md` for detailed Docker troubleshooting and workarounds.
+
 ## 🔍 Validation Features
 
 UnitForge provides comprehensive validation: