diff --git a/REAMDE.md b/REAMDE.md
index 6db45ff..2e6ce76 100644
--- a/REAMDE.md
+++ b/REAMDE.md
@@ -1,3 +1,48 @@
 # socket-samples
 
-A simple repo with examples of python sockets
+Socket programming examples in strict C90 and modern Python3.
+
+## Build & Run C90 Examples
+
+```
+make clean && make all
+```
+Builds 9 binaries in `build/` (strict `-std=c90 -pedantic -Wall -Wextra -Werror`).
+
+Port: **9999**
+
+All use the same **custom binary protocol**:
+- Header: `1-byte type + 2-byte BE16 length`
+- Types: `PING(0x01)`, `PONG(0x02)`, `METRIC_REQ(0x03)`, `METRIC_RESP(0x04)`, `SUBSCRIBE(0x05)`, `PUSH(0x06)`, `UNSUB(0x07)`, `ERROR(0xFF)`
+- Metrics: `cpu`, `memory`, `disk`, `loadavg`, `uptime` (simulated)
+
+### C90 Clients
+- `src/c90/metric_client.c`: Basic interactive TCP client (ping/get/quit).
+- `src/c90/metric_client_ansi.c`: Advanced TCP client w/ `select()` + unsubscribe.
+- `src/c90/metric_client_sub.c`: TCP client w/ live subscribe/push via `select()`.
+- `src/c90/metric_client_udp.c`: Full-featured UDP client (get/sub/unsub).
+- `src/c90/perf_client_udp.c`: UDP perf tester (`--flood` or subscribe mode, 30s throughput).
+
+### C90 Servers
+- `src/c90/metric_server.c`: Iterative TCP server (single client).
+- `src/c90/metric_server_fork.c`: Forking TCP server (multi-client).
+- `src/c90/metric_server_fork_sub.c`: Forking TCP server w/ subscribe/push.
+- `src/c90/metric_server_udp.c`: UDP server w/ subscriber management (`select()`).
+
+## Python Examples
+
+Run: `python3 src/python/<file>.py [host [port]]`
+
+Port: **9999** (metrics), **65432** (echo)
+
+### Echo (text protocol)
+- `src/python/echo_client.py`: Interactive TCP echo client.
+- `src/python/echo_server.py`: Iterative TCP echo server.
+
+### Metrics (same binary protocol as C90)
+- `src/python/metric_client.py`: Threaded TCP client (ping/get).
+- `src/python/metric_server.py`: Threaded multi-client TCP server.
+
+### Monitor (advanced w/ subscribe/push)
+- `src/python/mon_client.py`: Full TCP client (ping/get/sub).
+- `src/python/mon_server.py`: Threaded TCP server w/ subscribe/push support.