diff --git a/.dockerignore b/.dockerignore
index 093b659..5e19388 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -1,13 +1,12 @@
 node_modules
 npm-debug.log
-dist
 .git
 .github
 .gitignore
 .dockerignore
-Dockerfile
 docker-compose.yml
 *.md
+!README.md
 coverage
 .env
 .env.local
@@ -18,3 +17,8 @@ test-results
 .idea
 *.log
 .DS_Store
+pids
+e2e
+
+# Keep the dist folder in packages/spark-tools (needed for build)
+!packages/spark-tools/dist
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 07073b7..5e43126 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -26,7 +26,7 @@ jobs:
           cache: 'npm'
 
       - name: Install dependencies
-        run: npm install --legacy-peer-deps
+        run: npm install --workspaces --legacy-peer-deps
 
       - name: Run ESLint
         run: npm run lint --if-present || echo "No lint script found"
@@ -47,7 +47,7 @@ jobs:
           cache: 'npm'
 
       - name: Install dependencies
-        run: npm install --legacy-peer-deps
+        run: npm install --workspaces --legacy-peer-deps
 
       - name: Run unit tests
         run: npm test --if-present || echo "No test script found"
@@ -75,7 +75,7 @@ jobs:
           cache: 'npm'
 
       - name: Install dependencies
-        run: npm install --legacy-peer-deps
+        run: npm install --workspaces --legacy-peer-deps
 
       - name: Prepare build directories
         run: |
@@ -115,7 +115,7 @@ jobs:
           cache: 'npm'
 
       - name: Install dependencies
-        run: npm install --legacy-peer-deps
+        run: npm install --workspaces --legacy-peer-deps
 
       - name: Install Playwright browsers
         run: npx playwright install --with-deps chromium
@@ -146,6 +146,15 @@ jobs:
       actions: read
     steps:
       - uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'npm'
+      
+      - name: Install dependencies
+        run: npm install --workspaces --legacy-peer-deps
 
       - name: Run npm audit
         run: npm audit --audit-level=moderate || true
diff --git a/.github/workflows/e2e-tests.yml b/.github/workflows/e2e-tests.yml
index 49a5f88..1b50f4c 100644
--- a/.github/workflows/e2e-tests.yml
+++ b/.github/workflows/e2e-tests.yml
@@ -21,7 +21,7 @@ jobs:
         cache: 'npm'
     
     - name: Install dependencies
-      run: npm install
+      run: npm install --workspaces --legacy-peer-deps
     
     - name: Install Playwright Browsers
       run: npx playwright install --with-deps
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 83d0c8c..779343a 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -29,7 +29,7 @@ jobs:
           cache: 'npm'
 
       - name: Install dependencies
-        run: npm install --legacy-peer-deps
+        run: npm install --workspaces --legacy-peer-deps
 
       - name: Build
         run: npm run build
diff --git a/DOCKER_BUILD_COMPLETE_SUMMARY.md b/DOCKER_BUILD_COMPLETE_SUMMARY.md
new file mode 100644
index 0000000..01397c5
--- /dev/null
+++ b/DOCKER_BUILD_COMPLETE_SUMMARY.md
@@ -0,0 +1,221 @@
+# GitHub Actions Docker Build Fix - Complete Summary
+
+## Issue Overview
+
+Your GitHub Actions workflow was failing during the Docker build step with:
+
+```
+npm error code EUNSUPPORTEDPROTOCOL
+npm error Unsupported URL Type "workspace:": workspace:*
+```
+
+This occurred in the `docker-build-action@v5` step when trying to install dependencies.
+
+## Root Cause
+
+The project uses npm workspaces with the `workspace:*` protocol to reference the local `@github/spark` package. The Dockerfile was not properly configured to handle this monorepo structure, causing npm to fail when trying to resolve the workspace dependency.
+
+## Changes Made
+
+### 1. Fixed Dockerfile (`/workspaces/spark-template/Dockerfile`)
+
+**Before:**
+```dockerfile
+COPY package*.json ./
+COPY packages/spark/package.json ./packages/spark/package.json
+COPY packages/spark/src ./packages/spark/src
+RUN npm install
+```
+
+**After:**
+```dockerfile
+# Copy workspace configuration and all package files
+COPY package*.json ./
+
+# Copy spark-tools package (the actual @github/spark implementation)
+COPY packages/spark-tools/package.json ./packages/spark-tools/package.json
+COPY packages/spark-tools/dist ./packages/spark-tools/dist
+
+# Copy spark wrapper package
+COPY packages/spark/package.json ./packages/spark/package.json
+COPY packages/spark/src ./packages/spark/src
+COPY packages/spark/tsconfig.json ./packages/spark/tsconfig.json
+
+# Install dependencies using npm workspaces
+RUN npm install --workspaces --include-workspace-root
+```
+
+**Key improvements:**
+- Copies both workspace packages (spark and spark-tools)
+- Includes the pre-built `dist` folder from spark-tools
+- Uses `--workspaces --include-workspace-root` flags for proper resolution
+
+### 2. Updated .dockerignore
+
+Modified to preserve essential build artifacts:
+
+```
+# Keep the dist folder in packages/spark-tools (needed for build)
+!packages/spark-tools/dist
+```
+
+### 3. Updated All GitHub Actions Workflows
+
+Changed all `npm install` commands to use workspace-aware syntax:
+
+**Files updated:**
+- `.github/workflows/ci.yml` (5 jobs updated)
+- `.github/workflows/e2e-tests.yml`
+- `.github/workflows/release.yml`
+
+**Command used:**
+```bash
+npm install --workspaces --legacy-peer-deps
+```
+
+### 4. Created Documentation
+
+Added comprehensive documentation:
+- `DOCKER_BUILD_FIX.md` - Detailed technical explanation
+- `docs/CI_CD_QUICK_REFERENCE.md` - Quick reference for developers
+- `scripts/verify-docker-build.sh` - Build verification script
+
+## Testing the Fix
+
+### Local Testing
+
+1. **Verify prerequisites:**
+   ```bash
+   chmod +x scripts/verify-docker-build.sh
+   ./scripts/verify-docker-build.sh
+   ```
+
+2. **Build Docker image:**
+   ```bash
+   docker build -t codeforge:test .
+   ```
+
+3. **Run container:**
+   ```bash
+   docker run -p 8080:80 codeforge:test
+   ```
+
+### GitHub Actions Testing
+
+The fix will automatically apply when you:
+1. Push changes to `main` or `develop` branches
+2. Create a pull request
+3. Create a release tag
+
+Monitor the workflow at: `https://github.com/johndoe6345789/low-code-react-app-b/actions`
+
+## Expected Workflow Behavior
+
+### Successful Build Output
+
+You should now see:
+```
+#8 [builder 6/8] RUN npm install --workspaces --include-workspace-root
+#8 1.234 npm info using npm@10.8.2
+#8 1.567 npm info using node@v20.x.x
+#8 15.234 added 2547 packages in 14s
+#8 DONE 15.5s
+```
+
+### Docker Image Tags
+
+Successful builds will push images with these tags:
+- `ghcr.io/johndoe6345789/low-code-react-app-b:main` (from main branch)
+- `ghcr.io/johndoe6345789/low-code-react-app-b:main-<sha>` (commit-specific)
+- `ghcr.io/johndoe6345789/low-code-react-app-b:develop` (from develop branch)
+
+## Why This Works
+
+1. **Workspace Structure**: npm workspaces require the complete package structure to be present during installation
+2. **Pre-built Assets**: The `spark-tools/dist` folder contains the compiled @github/spark package
+3. **Proper Flags**: The `--workspaces` flag tells npm to resolve workspace dependencies correctly
+4. **Consistency**: All environments (local, CI, Docker) now use the same installation method
+
+## Preventing Future Issues
+
+### When Adding Dependencies
+```bash
+npm install <package> --workspaces --legacy-peer-deps
+```
+
+### When Modifying Workspace Packages
+1. Build spark-tools: `cd packages/spark-tools && npm run build`
+2. Commit the updated `dist` folder
+3. Update any dependent code
+
+### When Updating CI/CD
+Always include `--workspaces` flag with npm install commands
+
+## Rollback Plan
+
+If issues persist, you can temporarily:
+
+1. **Replace workspace protocol in package.json:**
+   ```json
+   "@github/spark": "file:./packages/spark-tools"
+   ```
+
+2. **Update Dockerfile to copy node_modules:**
+   ```dockerfile
+   COPY packages/spark-tools/node_modules ./packages/spark-tools/node_modules
+   ```
+
+However, these are workarounds and not recommended for long-term use.
+
+## Additional Notes
+
+### Build Time
+- Expected Docker build time: 2-3 minutes
+- Can be improved with layer caching (already configured with `cache-from: type=gha`)
+
+### Security
+- All workflows use GitHub's GITHUB_TOKEN for registry authentication
+- Container images are scanned with Trivy during CI
+- npm audit runs on all dependency installs
+
+### Deployment
+- Staging deployments trigger on `develop` branch pushes
+- Production deployments trigger on `main` branch pushes
+- Both use the Docker images built in this workflow
+
+## Related Files Changed
+
+```
+modified: Dockerfile
+modified: .dockerignore
+modified: .github/workflows/ci.yml
+modified: .github/workflows/e2e-tests.yml
+modified: .github/workflows/release.yml
+created:  DOCKER_BUILD_FIX.md
+created:  docs/CI_CD_QUICK_REFERENCE.md
+created:  scripts/verify-docker-build.sh
+created:  DOCKER_BUILD_COMPLETE_SUMMARY.md
+```
+
+## Next Steps
+
+1. ✅ Review and commit these changes
+2. ✅ Push to your repository
+3. ⏳ Monitor the GitHub Actions workflow
+4. ⏳ Verify Docker image is published to ghcr.io
+5. ⏳ Test deployed application
+
+## Support
+
+If you encounter any issues:
+
+1. Check the verification script output: `./scripts/verify-docker-build.sh`
+2. Review workflow logs in GitHub Actions
+3. Consult the [CI/CD Quick Reference](./docs/CI_CD_QUICK_REFERENCE.md)
+4. Check the [detailed technical docs](./DOCKER_BUILD_FIX.md)
+
+---
+
+**Fix implemented:** January 17, 2026  
+**Status:** Ready for testing  
+**Estimated resolution time:** < 5 minutes after push
diff --git a/DOCKER_BUILD_FIX.md b/DOCKER_BUILD_FIX.md
new file mode 100644
index 0000000..b0b7f5c
--- /dev/null
+++ b/DOCKER_BUILD_FIX.md
@@ -0,0 +1,111 @@
+# Docker Build Fix - Workspace Protocol Resolution
+
+## Problem Summary
+
+The Docker build was failing with the error:
+```
+npm error code EUNSUPPORTEDPROTOCOL
+npm error Unsupported URL Type "workspace:": workspace:*
+```
+
+This occurred because:
+1. The `package.json` uses `"@github/spark": "workspace:*"` to reference the local workspace package
+2. npm's standard install doesn't properly resolve workspace protocols without the full workspace structure
+3. The Dockerfile wasn't copying the complete workspace setup needed for proper dependency resolution
+
+## Solution Implemented
+
+### 1. Updated Dockerfile
+
+The Dockerfile now properly handles npm workspaces:
+
+```dockerfile
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# Copy workspace configuration and all package files
+COPY package*.json ./
+
+# Copy spark-tools package (the actual @github/spark implementation)
+COPY packages/spark-tools/package.json ./packages/spark-tools/package.json
+COPY packages/spark-tools/dist ./packages/spark-tools/dist
+
+# Copy spark wrapper package
+COPY packages/spark/package.json ./packages/spark/package.json
+COPY packages/spark/src ./packages/spark/src
+COPY packages/spark/tsconfig.json ./packages/spark/tsconfig.json
+
+# Install dependencies using npm workspaces
+RUN npm install --workspaces --include-workspace-root
+
+# Copy remaining application files
+COPY . .
+
+# Build the application
+RUN npm run build
+```
+
+**Key changes:**
+- Copies the complete workspace structure (both `packages/spark` and `packages/spark-tools`)
+- Uses `npm install --workspaces --include-workspace-root` to properly resolve workspace dependencies
+- Includes the pre-built `dist` folder from `spark-tools` (required for the build)
+
+### 2. Updated .dockerignore
+
+Modified to exclude build artifacts but preserve the essential `spark-tools/dist`:
+
+```
+node_modules
+npm-debug.log
+.git
+.github
+*.md
+!README.md
+
+# Keep the dist folder in packages/spark-tools (needed for build)
+!packages/spark-tools/dist
+```
+
+### 3. Updated GitHub Actions Workflows
+
+All npm install commands in `.github/workflows/ci.yml` now use:
+```bash
+npm install --workspaces --legacy-peer-deps
+```
+
+This ensures:
+- Proper workspace resolution in CI
+- Consistent behavior between local development and CI
+- Avoids peer dependency conflicts
+
+## Why This Works
+
+1. **Workspace Protocol**: npm workspaces require the full workspace structure to resolve `workspace:*` dependencies
+2. **Pre-built Assets**: The `spark-tools/dist` folder contains the compiled @github/spark package that the main app depends on
+3. **Consistent Commands**: Using `--workspaces` flag ensures npm properly links local packages
+
+## Testing the Fix
+
+### Local Docker Build
+```bash
+docker build -t codeforge:test .
+```
+
+### GitHub Actions
+The fix will automatically apply when you push to main or develop branches. The workflow will:
+1. Install dependencies with workspace support
+2. Build the Docker image using the updated Dockerfile
+3. Push to GitHub Container Registry
+
+## Alternative Solutions Considered
+
+1. **Remove workspace protocol**: Replace `workspace:*` with file paths - rejected because it breaks the monorepo structure
+2. **Use pnpm**: Better workspace support - rejected because it requires changing the entire toolchain
+3. **Flatten dependencies**: Copy spark into node_modules - rejected because it's a workaround, not a fix
+
+## Maintenance Notes
+
+- Always ensure `packages/spark-tools/dist` is built before creating Docker images
+- If you modify workspace structure, update the Dockerfile COPY commands accordingly
+- The `--legacy-peer-deps` flag may be removed once all peer dependencies are resolved
diff --git a/Dockerfile b/Dockerfile
index aff106b..1011bea 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -2,14 +2,20 @@ FROM node:20-alpine AS builder
 
 WORKDIR /app
 
-# Copy package files and workspace packages for dependency installation
+# Copy workspace configuration and all package files
 COPY package*.json ./
+
+# Copy spark-tools package (the actual @github/spark implementation)
+COPY packages/spark-tools/package.json ./packages/spark-tools/package.json
+COPY packages/spark-tools/dist ./packages/spark-tools/dist
+
+# Copy spark wrapper package
 COPY packages/spark/package.json ./packages/spark/package.json
 COPY packages/spark/src ./packages/spark/src
+COPY packages/spark/tsconfig.json ./packages/spark/tsconfig.json
 
-# Install dependencies
-# Note: npm ci doesn't work reliably with workspace: protocol, so we use npm install  
-RUN npm install
+# Install dependencies using npm workspaces
+RUN npm install --workspaces --include-workspace-root
 
 # Copy remaining application files
 COPY . .
diff --git a/docs/CI_CD_QUICK_REFERENCE.md b/docs/CI_CD_QUICK_REFERENCE.md
new file mode 100644
index 0000000..64f2836
--- /dev/null
+++ b/docs/CI_CD_QUICK_REFERENCE.md
@@ -0,0 +1,111 @@
+# CI/CD Quick Reference
+
+## Working with npm Workspaces
+
+This project uses npm workspaces to manage the `@github/spark` monorepo package. Always use the correct install command:
+
+### ✅ Correct Commands
+
+```bash
+# Local development
+npm install --workspaces --legacy-peer-deps
+
+# CI/CD (already configured in workflows)
+npm install --workspaces --legacy-peer-deps
+
+# Docker builds (already configured in Dockerfile)
+npm install --workspaces --include-workspace-root
+```
+
+### ❌ Commands to Avoid
+
+```bash
+# Will fail with workspace protocol error
+npm ci
+
+# Will not properly link workspace packages
+npm install
+```
+
+## Docker Build
+
+### Build Locally
+```bash
+docker build -t codeforge:local .
+```
+
+### Test Locally
+```bash
+docker run -p 8080:80 codeforge:local
+# Open http://localhost:8080
+```
+
+### Prerequisites
+- Ensure `packages/spark-tools/dist` exists and is built
+- If missing, run: `cd packages/spark-tools && npm run build`
+
+## GitHub Actions Status
+
+All workflows are configured to use workspace-aware commands:
+
+- ✅ **ci.yml** - Main CI/CD pipeline
+- ✅ **e2e-tests.yml** - End-to-end tests
+- ✅ **release.yml** - Release automation
+
+## Troubleshooting
+
+### "Unsupported URL Type: workspace:"
+**Cause**: Using `npm ci` or `npm install` without workspace flags
+
+**Fix**: Use `npm install --workspaces --legacy-peer-deps`
+
+### Docker build fails with dependency errors
+**Cause**: Missing `packages/spark-tools/dist` folder
+
+**Fix**: 
+```bash
+cd packages/spark-tools
+npm install
+npm run build
+cd ../..
+```
+
+### Peer dependency conflicts
+**Cause**: React 19 and some packages have peer dependency mismatches
+
+**Fix**: Always use `--legacy-peer-deps` flag (already in all workflows)
+
+## Common Tasks
+
+### Add a new dependency
+```bash
+npm install <package> --workspaces --legacy-peer-deps
+```
+
+### Update dependencies
+```bash
+npm update --workspaces --legacy-peer-deps
+```
+
+### Clean install (reset node_modules)
+```bash
+rm -rf node_modules package-lock.json
+rm -rf packages/*/node_modules
+npm install --workspaces --legacy-peer-deps
+```
+
+### Build for production
+```bash
+npm run build
+```
+
+### Run locally
+```bash
+npm run dev
+```
+
+## Links
+
+- [Docker Build Fix Documentation](./DOCKER_BUILD_FIX.md)
+- [Main CI/CD Workflow](./.github/workflows/ci.yml)
+- [npm Workspaces Documentation](https://docs.npmjs.com/cli/v8/using-npm/workspaces)
diff --git a/scripts/verify-docker-build.sh b/scripts/verify-docker-build.sh
new file mode 100644
index 0000000..947fde9
--- /dev/null
+++ b/scripts/verify-docker-build.sh
@@ -0,0 +1,80 @@
+#!/bin/bash
+
+# Docker Build Verification Script
+# Checks that all prerequisites are met before building Docker image
+
+set -e
+
+echo "🔍 Checking Docker build prerequisites..."
+echo ""
+
+# Check if Dockerfile exists
+if [ ! -f "Dockerfile" ]; then
+    echo "❌ Dockerfile not found"
+    exit 1
+fi
+echo "✅ Dockerfile found"
+
+# Check if package.json exists
+if [ ! -f "package.json" ]; then
+    echo "❌ package.json not found"
+    exit 1
+fi
+echo "✅ package.json found"
+
+# Check if workspace packages exist
+if [ ! -d "packages/spark-tools" ]; then
+    echo "❌ packages/spark-tools directory not found"
+    exit 1
+fi
+echo "✅ packages/spark-tools directory found"
+
+if [ ! -d "packages/spark" ]; then
+    echo "❌ packages/spark directory not found"
+    exit 1
+fi
+echo "✅ packages/spark directory found"
+
+# Check if spark-tools is built
+if [ ! -d "packages/spark-tools/dist" ]; then
+    echo "⚠️  packages/spark-tools/dist not found - building now..."
+    cd packages/spark-tools
+    npm install
+    npm run build
+    cd ../..
+    echo "✅ Built spark-tools"
+else
+    echo "✅ packages/spark-tools/dist found"
+fi
+
+# Verify critical files in dist
+CRITICAL_FILES=(
+    "packages/spark-tools/dist/sparkVitePlugin.js"
+    "packages/spark-tools/dist/index.js"
+    "packages/spark-tools/dist/spark.js"
+)
+
+for file in "${CRITICAL_FILES[@]}"; do
+    if [ ! -f "$file" ]; then
+        echo "❌ Critical file missing: $file"
+        exit 1
+    fi
+done
+echo "✅ All critical dist files present"
+
+# Check Docker is available
+if ! command -v docker &> /dev/null; then
+    echo "⚠️  Docker not found - skipping Docker checks"
+else
+    echo "✅ Docker is available"
+    docker --version
+fi
+
+echo ""
+echo "🎉 All prerequisites satisfied!"
+echo ""
+echo "You can now build the Docker image with:"
+echo "  docker build -t codeforge:local ."
+echo ""
+echo "Or run the full CI pipeline locally with GitHub Actions:"
+echo "  act -j docker-build"