From 645e4c956ce5ed5ff9ab27b85de802652c724213 Mon Sep 17 00:00:00 2001
From: Martin McCaffery <martin.mccaffery@think-ahead.tech>
Date: Tue, 27 Jan 2026 16:41:18 +0100
Subject: [PATCH] Update README

---
 README.md | 62 +++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 51 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 100ef85..4c99430 100644
--- a/README.md
+++ b/README.md
@@ -4,20 +4,60 @@ Documentation for the edgeDeveloperFramework (eDF) project and the resulting Edg
 
 ## Quick Start
 
+### Development Environment
+
+Install and enter [Devbox](https://www.jetify.com/devbox):
 ```bash
-# Install dependencies
-task deps
-
-# Start local development server
-task serve
-
-# Run tests
-task test
-
-# Build production site
-task build
+curl -fsSL https://get.jetify.com/devbox | bash
+devbox shell
 ```
 
+Devbox installs Hugo, Node.js, Go, and all required tools. First-time setup requires sudo for the Nix daemon (one-time only).
+
+To avoid entering the shell, run commands directly:
+```bash
+devbox run task serve
+```
+
+### Local Development
+
+```bash
+task deps:install    # Install dependencies
+task serve          # Start dev server at http://localhost:1313 (hot-reloading)
+task test:quick     # Run tests
+task build          # Build production site
+```
+
+## Architecture Diagrams (LikeC4)
+
+[LikeC4](https://likec4.dev/) generates interactive architecture diagrams from text-based [C4 models](https://c4model.com/). Create or edit diagrams:
+
+```bash
+cd resources/edp-likec4     # Platform architecture
+npm install                 # First time only
+npm start                   # Preview at http://localhost:5173
+```
+
+Edit `.c4` files to define systems and views. Generate web components for Hugo:
+```bash
+task likec4:generate
+```
+
+Embed in Markdown pages:
+```markdown
+{{</* likec4-view view="overview" project="architecture" */>}}
+```
+
+See [LikeC4 documentation](https://likec4.dev/) for detailed syntax and [README-likec4.md](doc/README-likec4.md) for project-specific details.
+
+## Deployment
+
+Deployment is automatic via ArgoCD. Push to `main` triggers CI/CD build and deployment within 5-10 minutes.
+
+**Infrastructure Configuration:**
+- ArgoCD is configured within [stacks-instances](https://edp.buildth.ing/DevFW-CICD/stacks-instances/src/branch/main/otc/edp.buildth.ing/registry/docs.yaml)
+- Documentation stack definition: [./argocd-stack/](https://edp.buildth.ing/DevFW-CICD/website-and-documentation/src/branch/main/argocd-stack)
+
 ## Documentation
 
 * [Developer Guide](doc/README-developer.md)