diff --git a/README.md b/README.md
new file mode 100644
index 0000000..90a9fdd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,45 @@
+# go-ws
+
+WebSocket hub for real-time streaming in Go. Implements the hub pattern with centralised connection management, named channel pub/sub, token-based authentication on upgrade, client-side reconnection with exponential backoff, and a Redis pub/sub bridge for coordinating broadcasts across multiple hub instances. The envelope pattern with a per-bridge source ID prevents loop amplification when the Redis bridge is in use.
+
+**Module**: `forge.lthn.ai/core/go-ws`
+**Licence**: EUPL-1.2
+**Language**: Go 1.25
+
+## Quick Start
+
+```go
+import "forge.lthn.ai/core/go-ws"
+
+hub := ws.NewHub()
+go hub.Run(ctx)
+
+// Mount on any HTTP mux
+http.HandleFunc("/ws", hub.Handler())
+
+// Send process output to subscribers of "process:abc"
+hub.SendProcessOutput("abc", "output line")
+
+// Redis bridge for multi-instance coordination
+bridge, _ := ws.NewRedisBridge(hub, ws.RedisConfig{Addr: "localhost:6379"})
+bridge.Start(ctx)
+```
+
+## Documentation
+
+- [Architecture](docs/architecture.md) — hub pattern, channel subscriptions, authentication, Redis bridge, envelope loop prevention
+- [Development Guide](docs/development.md) — prerequisites, test patterns, coding standards
+- [Project History](docs/history.md) — completed phases with commit hashes, known limitations
+
+## Build & Test
+
+```bash
+go test ./...
+go test -race ./...
+go test -bench=. -benchmem ./...
+go build ./...
+```
+
+## Licence
+
+European Union Public Licence 1.2 — see [LICENCE](LICENCE) for details.