From 914421d7a54f332c8b423cfe8daa85b4551258dc Mon Sep 17 00:00:00 2001
From: Sebastian Mark <smark@posteo.net>
Date: Sun, 20 Oct 2024 19:26:14 +0200
Subject: [PATCH] doc: update README with client commands and server messages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- add table of contents for better navigation
- document client commands with JSON examples
- describe server messages and their structure

🤖
---
 README.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/README.md b/README.md
index 0362d80..39aee92 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,8 @@
 
 A pomodoro server written in Go
 
+[[_TOC_]]
+
 ## Installation
 
 `go install git.smsvc.net/pomodoro/GoTomato@latest`
@@ -10,6 +12,42 @@ A pomodoro server written in Go
 
 See `GoTomato --help` for Parameters
 
+## Client Commands and Server Messages
+
+This section describes the WebSocket commands that clients can send to the Pomodoro server and the messages that the server sends to clients during a Pomodoro session.
+
+### Message Format
+
+Both client commands (sent to the server) and server messages (sent to the client) use the JSON format. The structure of these messages are described in the sections below.
+
+
+### Client Commands
+
+Clients communicate with the server by sending JSON-encoded commands. Each command must include a `command` field specifying the action to perform. Here are the available commands:
+
+| Command  | Action                              | Example Sent by Client            |
+|----------|-------------------------------------|-----------------------------------|
+| `start`  | Starts a new Pomodoro session       | `{"command": "start"}`            |
+| `pause`  | Pauses the current session          | `{"command": "pause"}`            |
+| `resume` | Resumes a paused session            | `{"command": "resume"}`           |
+| `reset`  | Stops and resets the current session| `{"command": "reset"}`            |
+
+### Server Messages
+
+The server sends JSON-encoded messages to all connected clients to update them on the current state of the Pomodoro session.
+These messages contain the following fields:
+
+- mode: Indicates the current phase of the Pomodoro session ("Work", "ShortBreak", "LongBreak", or "none" if no session is running).
+- session: The current session number (e.g., 1 for the first work session).
+- max_session: The total number of sessions for the current Pomodoro cycle (e.g., 4 if the cycle consists of 4 work/break sessions).
+- time_left: The remaining time for the current mode, in seconds (e.g., 900 for 15 minutes).
+
+| Message Type          | Sent by Server                                   | Example                                                              |
+| --------------------- | ------------------------------------------------ | ---------------------------------------------------                  |
+| Welcome Message       | Upon initial client connection                   | `{"mode": "none", "session": 0, "max_session": 0, "time_left": 0}`   |
+| Session Update        | Periodically during a session                    | `{"mode": "Work", "session": 1, "max_session": 4, "time_left": 900}` |
+| Session End/Reset     | After session completes or is reset              | `{"mode": "none", "session": 0, "max_session": 0, "time_left": 0}`   |
+
 ## Testing
 
 ```