doc: update README with client commands and server messages

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

🤖

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
 
 ```