Add comprehensive documentation for fx-test repo

docs/usage.md

@@ -0,0 +1,69 @@
+# 📖 Usage Guide
+
+The **fx-test** stack exposes two primary interfaces:
+
+1. **WebSocket** – Real‑time event channel.
+2. **HTTP** – RESTful configuration and monitoring.
+
+## 1️⃣ WebSocket API
+
+The WebSocket endpoint is available on port `8080`. Common message types:
+
+| Message Type | Description |
+|--------------|-------------|
+| `ping` | Health check; server replies with `pong`. |
+| `subscribe` | Subscribe to a topic; server sends updates. |
+| `publish` | Broadcast a message to all clients. |
+
+Example using Node.js:
+
+```js
+const ws = require("ws");
+const socket = new ws("ws://localhost:8080");
+
+socket.on("open", () => socket.send(JSON.stringify({type:"ping"}));
+
+socket.on("message", m => console.log("Received: ", m));
+```
+
+## 2️⃣ HTTP API
+
+### Health
+
+```bash
+GET /health
+```
+
+Response:
+```json
+{"status":"ok","uptime":123456}
+```
+
+### Status
+
+```bash
+GET /status
+```
+
+Returns the current number of connected WebSocket clients and processing metrics.
+
+## 3️⃣ Configuring via ENV
+
+The stack reads the following environment variables:
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| **PORT** | `8080` | WebSocket port |
+| **HTTP_PORT** | `8090` | HTTP listening port |
+| **REGISTRY** | `docker.io` | Registry to fetch Docker images |
+| **DEBUG** | `false` | Enable debug logging |
+
+Set the environment variables in a `.env` file at the repo root or export them in your shell before running `run_dev.sh`.
+
+---
+
+## 4️⃣ Extending the Stack
+
+1. **Add a new service** – Place a `Dockerfile` in `fluxer/` and reference it in the `docker-compose.yml`.
+2. **Modify the relay** – Edit the Erlang source in `fluxer_relay/src/relay/`. After editing, recompile with `rebar3 do compile, release` and rebuild the Docker image.
+3. **Update the CI** – Extend `ci/workflows/**.py` to run any new tests.