diff --git a/README.md b/README.md
index f77a5845..76058b35 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,10 @@
-# SCADA System — Design Documentation
+# ScadaBridge
+
+ScadaBridge is a centrally-managed, distributed SCADA configuration and deployment platform built on Akka.NET, running across a central cluster and multiple site clusters in a hub-and-spoke topology.
 
 ## Overview
 
-This document serves as the master index for the SCADA system design. The system is a centrally-managed, distributed SCADA configuration and deployment platform built on Akka.NET, running across a central cluster and multiple site clusters in a hub-and-spoke topology.
+This repository is the full **implementation** project for ScadaBridge — the C#/.NET source (`src/`), tests (`tests/`), deployable Docker topology (`docker/`, `docker-env2/`, `infra/`), and the design documentation (`docs/`) that the code implements. This README is the master index: it links the per-component **design specs** (the spec the code in `src/` implements) and shows the system architecture. The solution file is `ZB.MOM.WW.ScadaBridge.slnx`.
 
 ### Technology Stack
 
@@ -24,6 +26,38 @@ This document serves as the master index for the SCADA system design. The system
 - Central cluster: 2-node active/standby behind a load balancer.
 - Site clusters: 2-node active/standby, headless (no UI).
 
+## Repository Layout
+
+| Path | Contents |
+|------|----------|
+| `src/` | C#/.NET implementation — one project per component (`ZB.MOM.WW.ScadaBridge.<Component>`). Solution: `ZB.MOM.WW.ScadaBridge.slnx`. |
+| `tests/` | Unit and integration test projects. |
+| `docs/` | Design documentation — `docs/requirements/` (high-level + per-component specs, the spec the code implements), `docs/test_infra/`, `docs/plans/`. |
+| `docker/` | Primary 8-node cluster topology (2 central + 3 sites × 2 nodes + Traefik) + `deploy.sh`. |
+| `docker-env2/` | Minimal second cluster (2 central + 1 site) for exercising Transport (#24) against a real second environment. |
+| `infra/` | Local test services (MS SQL, LDAP, OPC UA, SMTP, REST API, Traefik). |
+| `deploy/` | Production/on-host deployment artifacts (e.g. `wonder-app-vd03/`). |
+| `AkkaDotNet/` | Akka.NET reference notes. |
+
+## Build, Test & Run
+
+```bash
+# Build the solution
+dotnet build ZB.MOM.WW.ScadaBridge.slnx
+
+# Run the tests
+dotnet test ZB.MOM.WW.ScadaBridge.slnx
+
+# Bring up the primary local cluster (builds the scadabridge:latest image + recreates containers)
+bash docker/deploy.sh        # central load balancer at http://localhost:9000
+
+# Drive the system from the CLI (reads ~/.scadabridge/config.json; test user has all roles)
+dotnet run --project src/ZB.MOM.WW.ScadaBridge.CLI -- \
+  --username multi-role --password password template list
+```
+
+See [`docker/README.md`](docker/README.md) for ports and management commands, and [`src/ZB.MOM.WW.ScadaBridge.CLI/README.md`](src/ZB.MOM.WW.ScadaBridge.CLI/README.md) for the full CLI reference.
+
 ## Local Test Environments
 
 Two Docker-based cluster topologies are available for local development and testing: