From 1a6e929f56ba9d60f8d1d0d9241ae2dc6b8b0bdf Mon Sep 17 00:00:00 2001
From: clawbot <clawbot@git.eeqj.de>
Date: Tue, 10 Feb 2026 17:53:48 -0800
Subject: [PATCH] docs: update README API spec for unified command endpoint

- Document all C2S commands with required/optional fields table
- Remove separate join/part/nick/topic endpoint docs
- Update /channels/all to /channels
- Update /register to /session
---
 README.md | 41 +++++++++++++++++++++++++++++++++--------
 1 file changed, 33 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index a72ee37..66a6a6b 100644
--- a/README.md
+++ b/README.md
@@ -354,7 +354,7 @@ curl -s "http://localhost:8080/api/v1/messages?timeout=15" \
 
 ```
 POST /api/v1/session         — Create session { "nick": "..." }
-                                → { session_id, client_id, nick, token }
+                                → { id, nick, token }
                                 Token is opaque (random), not JWT.
                                 Token implicitly identifies the client.
 ```
@@ -374,8 +374,34 @@ GET  /api/v1/messages        — Single message stream (long-poll, 15s timeout)
                                 Delivers from the calling client's queue
                                 (identified by auth token)
                                 Query params: ?after=<message-id>&timeout=15
-POST /api/v1/messages        — Send a message (IRC command in body)
-                                Body: { "command": "PRIVMSG", "to": "#channel", "body": ["..."] }
+POST /api/v1/messages        — Send any C2S command (dispatched by "command" field)
+```
+
+All client-to-server commands use `POST /api/v1/messages` with a `command`
+field. There are no separate endpoints for join, part, nick, topic, etc.
+
+| Command   | Required Fields     | Optional Fields | Description |
+|-----------|---------------------|-----------------|-------------|
+| `PRIVMSG` | `to`, `body`        | `meta`          | Message to channel (`#name`) or user (nick) |
+| `NOTICE`  | `to`, `body`        | `meta`          | Notice (must not trigger auto-reply) |
+| `JOIN`    | `to`                |                 | Join a channel (creates if nonexistent) |
+| `PART`    | `to`                | `body`          | Leave a channel |
+| `NICK`    | `body`              |                 | Change nickname — `body: ["newnick"]` |
+| `TOPIC`   | `to`, `body`        |                 | Set channel topic |
+| `MODE`    | `to`, `params`      |                 | Set channel/user modes |
+| `KICK`    | `to`, `params`      | `body`          | Kick user — `params: ["nick"]`, `body: ["reason"]` |
+| `PING`    |                     |                 | Keepalive (server responds with PONG) |
+| `PUBKEY`  | `body`              |                 | Announce signing key — `body: {"alg":..., "key":...}` |
+
+Examples:
+
+```json
+{"command": "PRIVMSG", "to": "#channel", "body": ["hello world"]}
+{"command": "JOIN", "to": "#channel"}
+{"command": "PART", "to": "#channel"}
+{"command": "NICK", "body": ["newnick"]}
+{"command": "TOPIC", "to": "#channel", "body": ["new topic text"]}
+{"command": "PING"}
 ```
 
 Messages are immutable — no edit or delete endpoints.
@@ -391,14 +417,13 @@ GET  /api/v1/history         — Fetch history for a target (channel or DM)
 #### Channels
 
 ```
-GET  /api/v1/channels/all              — List all server channels
-POST /api/v1/channels/join             — Join a channel { "channel": "#name" }
-                                         Creates the channel if it doesn't exist.
-DELETE /api/v1/channels/{name}         — Part (leave) a channel
-                                         Channel is destroyed when last member leaves.
+GET  /api/v1/channels              — List all server channels
 GET  /api/v1/channels/{name}/members   — Channel member list
 ```
 
+Join and part are handled via `POST /api/v1/messages` with `JOIN` and `PART`
+commands (see Messages above).
+
 #### Server Info
 
 ```