Rewrite README.md sentence by sentence (closes #190)

README.md is rewritten from scratch against the rules on issue 190 and
checked statement by statement against the code on next. It leads with
what the program is and how to use it, puts every endpoint, command,
numeric reply, mode and setting in reference sections, and ends with
development and testing. Where the old text disagreed with the code,
the code decides; the PR body lists each case. The hashcash examples
are real 20-bit stamps. REPO_POLICIES.md and CONVENTIONS.md are copies
of shared documents and are untouched.

Model: fable-5-1

schema/README.md

@@ -1,98 +1,166 @@
-# Message Schemas
+# Message schemas
 
-JSON Schema definitions (draft 2020-12) for the neoirc protocol. Messages use
+This directory holds JSON Schema files (draft 2020-12) for the messages that the
-**IRC command names and numeric reply codes** (RFC 1459/2812) encoded as JSON
+neoirc HTTP API carries. `message.json` describes the fields that every message
-over HTTP.
+can have. `commands/` has files for some commands. `numerics/` has files for
+some of the numeric replies. A numeric reply is a server reply named by a
+three-digit number, such as `001`. `README.md` at the repository root documents
+the protocol.
 
-## Envelope
+The server can also run an IRC listener for ordinary IRC clients. The IRC
+listener sends plain IRC lines, which these files do not describe.
 
-Every message is a JSON object with a `command` field. The format maps directly
+## Message fields
-to IRC wire format:
+
+Every message is one JSON object, which `message.json` calls the envelope. These
+are the fields it can have:
+
+- `command`: the IRC command name, such as `PRIVMSG`, or the name of a numeric
+  reply, such as `RPL_WELCOME`. Always present.
+- `code`: the number of a numeric reply, such as `1` for `RPL_WELCOME`. Absent
+  on other messages.
+- `id`: the message's UUID, a unique ID that the server assigns.
+- `from`: the sender's nick, or the server name on a server message.
+- `to`: the target, such as a channel name starting with `#` or a nick.
+- `params`: an array of strings with the message's other parameters, in order.
+  `KICK` events and many numeric replies have it. The HTTP API ignores `params`
+  sent by a client.
+- `body`: an array of strings. It is never a bare string. In a `PRIVMSG` or
+  `NOTICE`, each string is one line of text.
+- `ts`: the time the server stored the message. It is an RFC 3339 time in UTC,
+  such as `2026-10-27T12:00:00.123Z`.
+- `meta`: an object of extra data, such as a hashcash stamp in `meta.hashcash`.
+  A hashcash stamp is a short string that takes a computer some work to make. A
+  `PRIVMSG` to a channel with mode `+H` needs one. The HTTP API relays the
+  `meta` of a `PRIVMSG` or `NOTICE` unchanged. It drops the `meta` of every
+  other command.
+
+Here is one `PRIVMSG` as the IRC listener sends it and as the HTTP API sends it.
+The JSON leaves out `id`, `ts` and `meta`:
 
 ```
-IRC:  :nick PRIVMSG #channel :hello world
+IRC:  :alice!alice@* PRIVMSG #general :hello world
-JSON: {"command": "PRIVMSG", "from": "nick", "to": "#channel", "body": ["hello world"]}
+JSON: {"command": "PRIVMSG", "from": "alice", "to": "#general", "body": ["hello world"]}
-
-IRC:  :server 353 nick = #channel :user1 @op1 +voice1
-JSON: {"command": "353", "to": "nick", "params": ["=", "#channel"], "body": ["user1 @op1 +voice1"]}
-
-Multiline:  {"command": "PRIVMSG", "to": "#ch", "body": ["line 1", "line 2"]}
-Structured: {"command": "PUBKEY", "body": {"alg": "ed25519", "key": "base64..."}}
 ```
 
-Common fields (see `message.json` for full schema):
+In the JSON, a numeric reply has its name in `command` and its number in `code`.
+This `353` reply lists the members of `#general`. The JSON again leaves out
+`id`, `ts` and `meta`:
 
-| Field     | Type            | Description                                          |
+```
-| --------- | --------------- | ---------------------------------------------------- |
+{"command": "RPL_NAMREPLY", "code": 353, "from": "neoirc", "to": "alice",
-| `id`      | string (uuid)   | Server-assigned message UUID                         |
+ "params": ["=", "#general"], "body": ["@op1!op1@host1 alice!alice@host2"]}
-| `command` | string          | IRC command or 3-digit numeric code                  |
+```
-| `from`    | string          | Source nick or server name (IRC prefix)              |
-| `to`      | string          | Target: #channel or nick                             |
-| `params`  | string[]        | Middle parameters (mainly for numerics)              |
-| `body`    | array \| object | Structured body — never a raw string (see below)     |
-| `ts`      | string          | ISO 8601 timestamp (server-assigned, not in raw IRC) |
-| `meta`    | object          | Extensible metadata (signatures, hashes, etc.)       |
 
-**Structured bodies:** `body` is always an array of strings (for text) or an
+A `PRIVMSG` whose `body` has two strings is a two-line message:
-object (for structured data like PUBKEY). Never a raw string. This enables:
 
-- Multiline messages without escape sequences
+```
-- Deterministic canonicalization via RFC 8785 JCS for signing
+{"command": "PRIVMSG", "to": "#general", "body": ["line one", "line two"]}
-- Structured data where needed
+```
 
-## Commands
+## Files
 
-IRC commands used for client↔server and server↔server communication.
+Commands, in `commands/`:
 
-| Command   | File                    | RFC         | Description                |
+- `PRIVMSG.json`: a message to a channel or a user.
-| --------- | ----------------------- | ----------- | -------------------------- |
+- `NOTICE.json`: a notice, which is a message that a client must not answer
-| `PRIVMSG` | `commands/PRIVMSG.json` | 1459 §4.4.1 | Message to channel or user |
+  automatically.
-| `NOTICE`  | `commands/NOTICE.json`  | 1459 §4.4.2 | Notice (no auto-reply)     |
+- `JOIN.json`: a user joined a channel.
-| `JOIN`    | `commands/JOIN.json`    | 1459 §4.2.1 | Join a channel             |
+- `PART.json`: a user left a channel.
-| `PART`    | `commands/PART.json`    | 1459 §4.2.2 | Leave a channel            |
+- `QUIT.json`: a user left the server.
-| `QUIT`    | `commands/QUIT.json`    | 1459 §4.1.6 | User disconnected          |
+- `NICK.json`: a user changed nick.
-| `NICK`    | `commands/NICK.json`    | 1459 §4.1.2 | Change nickname            |
+- `TOPIC.json`: a channel topic was set.
-| `TOPIC`   | `commands/TOPIC.json`   | 1459 §4.2.4 | Get/set channel topic      |
+- `MODE.json`: a channel mode was changed.
-| `MODE`    | `commands/MODE.json`    | 1459 §4.2.3 | Set channel/user modes     |
+- `KICK.json`: a channel operator removed a user from a channel.
-| `KICK`    | `commands/KICK.json`    | 1459 §4.2.8 | Kick user from channel     |
+- `PING.json`: a check that the server still answers.
-| `PING`    | `commands/PING.json`    | 1459 §4.6.2 | Keepalive                  |
+- `PONG.json`: the answer to a `PING`.
-| `PONG`    | `commands/PONG.json`    | 1459 §4.6.3 | Keepalive response         |
+- `PUBKEY.json`: an announcement of a user's public signing key. The server has
-| `PUBKEY`  | `commands/PUBKEY.json`  | (extension) | Announce/relay signing key |
+  no such command. It answers a `PUBKEY` with `ERR_UNKNOWNCOMMAND` (`421`).
 
-## Numeric Replies
+Numeric replies, in `numerics/`:
 
-Three-digit codes for server responses, per IRC convention.
+- `001.json`: `RPL_WELCOME`, which welcomes a new user.
+- `002.json`: `RPL_YOURHOST`, the server's name and version.
+- `003.json`: `RPL_CREATED`, which says when the server was created.
+- `004.json`: `RPL_MYINFO`, the server's version and its lists of modes.
+- `322.json`: `RPL_LIST`, one channel in the answer to `LIST`.
+- `323.json`: `RPL_LISTEND`, the end of the answer to `LIST`.
+- `332.json`: `RPL_TOPIC`, a channel's topic.
+- `353.json`: `RPL_NAMREPLY`, a channel's members.
+- `366.json`: `RPL_ENDOFNAMES`, the end of the member list.
+- `372.json`: `RPL_MOTD`, one line of the message of the day.
+- `375.json`: `RPL_MOTDSTART`, the start of the message of the day.
+- `376.json`: `RPL_ENDOFMOTD`, the end of the message of the day.
+- `401.json`: `ERR_NOSUCHNICK`, the nick does not exist.
+- `403.json`: `ERR_NOSUCHCHANNEL`, the channel does not exist.
+- `433.json`: `ERR_NICKNAMEINUSE`, the nick is taken.
+- `442.json`: `ERR_NOTONCHANNEL`, the user is not on that channel.
+- `482.json`: `ERR_CHANOPRIVSNEEDED`, the user is not a channel operator.
 
-### Success / Informational (0xx–3xx)
+## Where the files differ from the HTTP API
 
-| Code  | Name           | File                | Description                    |
+Where a schema file and the HTTP API disagree, the HTTP API is right:
-| ----- | -------------- | ------------------- | ------------------------------ |
-| `001` | RPL_WELCOME    | `numerics/001.json` | Welcome after session creation |
-| `002` | RPL_YOURHOST   | `numerics/002.json` | Server host info               |
-| `003` | RPL_CREATED    | `numerics/003.json` | Server creation date           |
-| `004` | RPL_MYINFO     | `numerics/004.json` | Server info and modes          |
-| `322` | RPL_LIST       | `numerics/322.json` | Channel list entry             |
-| `323` | RPL_LISTEND    | `numerics/323.json` | End of channel list            |
-| `332` | RPL_TOPIC      | `numerics/332.json` | Channel topic                  |
-| `353` | RPL_NAMREPLY   | `numerics/353.json` | Channel member list            |
-| `366` | RPL_ENDOFNAMES | `numerics/366.json` | End of NAMES list              |
-| `372` | RPL_MOTD       | `numerics/372.json` | MOTD line                      |
-| `375` | RPL_MOTDSTART  | `numerics/375.json` | Start of MOTD                  |
-| `376` | RPL_ENDOFMOTD  | `numerics/376.json` | End of MOTD                    |
 
-### Errors (4xx)
+- `message.json` and the files in `numerics/` put the three-digit code in
+  `command`. They have no `code` field. The HTTP API puts the reply's name in
+  `command` and its number in `code`.
+- `message.json` allows an object as `body`. The HTTP API reads only arrays of
+  strings. A `PRIVMSG` with an object as `body` gets `ERR_NOTEXTTOSEND` (`412`).
+- `message.json` says `to` is a channel or a nick. A `WALLOPS` message has `*`
+  there.
+- `message.json` allows `meta` on every message. The HTTP API keeps a client's
+  `meta` only on a `PRIVMSG` or `NOTICE`.
+- `message.json` describes signature fields in `meta`. The server never checks a
+  signature.
+- `message.json` does not describe `meta.hashcash`. The HTTP API reads it in a
+  `PRIVMSG` to a channel with mode `+H`.
+- `JOIN.json` has no `body`. A client's `JOIN` can carry the channel key in
+  `body`. When a user joins, the `JOIN` event repeats the channel name in
+  `body`.
+- `JOIN.json` allows a channel name of any length. The server allows at most 63
+  characters after the `#`. It answers a longer name with `ERR_NOSUCHCHANNEL`
+  (`403`).
+- `KICK.json` puts the kicked nick in `params`. The HTTP API reads a client's
+  `KICK` from `body`: the nick, then an optional reason.
+- `MODE.json` puts the mode change in `params`. The HTTP API uses `body`
+  instead. A client sends the change and any value as separate strings, such as
+  `"+o"` and `"bob"`. In a `MODE` event, `body` holds the change as one string,
+  such as `"+o bob"`, or as two strings, such as `"+k"` and `"secret"`.
+- `NOTICE.json` allows `*` as `to`. The server answers a `NOTICE` to `*` with
+  `ERR_NOSUCHNICK` (`401`).
+- `NOTICE.json` has an example notice from the server to `*`. The server sends
+  no such notice.
+- `PING.json` and `PONG.json` describe a token that the `PONG` repeats. The HTTP
+  API ignores the `body` of a `PING`. Its answer is the HTTP response
+  `{"command": "PONG", "from": "<server name>"}`.
+- `PING.json` and `PONG.json` also describe messages between servers. The server
+  does not connect to other IRC servers.
+- `PUBKEY.json` describes a command the server does not have.
+- `QUIT.json` says that `QUIT` comes only from the server. A client can send it
+  too, to end its session. A client's `QUIT` can carry a reason in `body`.
+- `TOPIC.json` says a `TOPIC` without a `body` queries the topic. The HTTP API
+  answers such a `TOPIC` with `ERR_NEEDMOREPARAMS` (`461`).
+- `TOPIC.json` says an empty array clears the topic. The HTTP API answers `[]`
+  with `ERR_NEEDMOREPARAMS` (`461`). A `body` of `[""]` clears the topic.
+- `003.json` describes the server's creation date. The HTTP API sends the date
+  the server last started.
+- `004.json` has example mode lists. The HTTP API sends an empty string as the
+  user modes and `ikmnostl` as the channel modes.
+- `322.json` says `LIST` gets one reply per channel. The server leaves out a
+  secret channel, one with mode `+s`, unless the user is on it.
+- `332.json` says `RPL_TOPIC` answers a `TOPIC` query. The HTTP API has no such
+  query. It sends `RPL_TOPIC` after a client sets the topic, and after a `JOIN`
+  to a channel that has one.
+- `353.json` says `body` lists nicks. The HTTP API lists `nick!user@host` in
+  place of each nick, such as `@op1!op1@host1`.
+- `353.json` says the first parameter marks a channel as public, private or
+  secret. The server always sends `=`, the mark for a public channel.
+- `376.json` gives the text as `End of /MOTD command`. The HTTP API adds a full
+  stop.
+- `401.json` gives the text as `No such nick/channel`. The server sends
+  `No such nick` in answer to a `PRIVMSG` or `NOTICE` to an unknown nick.
+- `433.json` has an example with `*` as `to`. The HTTP API sends `433` only in
+  answer to a `NICK`, with the user's nick as `to`.
 
-| Code  | Name                 | File                | Description             |
+The HTTP API also accepts some messages that the files do not allow, such as a
-| ----- | -------------------- | ------------------- | ----------------------- |
+`JOIN` whose `to` has no `#`.
-| `401` | ERR_NOSUCHNICK       | `numerics/401.json` | No such nick/channel    |
-| `403` | ERR_NOSUCHCHANNEL    | `numerics/403.json` | No such channel         |
-| `433` | ERR_NICKNAMEINUSE    | `numerics/433.json` | Nickname already in use |
-| `442` | ERR_NOTONCHANNEL     | `numerics/442.json` | Not on that channel     |
-| `482` | ERR_CHANOPRIVSNEEDED | `numerics/482.json` | Not channel operator    |
-
-## Federation (S2S)
-
-Server-to-server messages use the same command format. Federated servers relay
-messages with an additional `origin` field in `meta` to track the source server.
-The PING/PONG commands serve as inter-server keepalives. State sync after link
-establishment uses a burst of JOIN, NICK, TOPIC, and MODE commands.