Rewrite schema/README.md sentence by sentence

Rewrite the description of the JSON Schema directory from scratch,
without tables, as a reader of the files needs it. Describe the
envelope as the server sends it: the reply name in `command` and the
number in `code`. Drop the federation section, which describes nothing
the server does. List where each schema file disagrees with the
server, so a reader is not misled; the files themselves are unchanged.

Part of #190.

Model: fable-5-1

schema/README.md

@@ -1,98 +1,95 @@
-# Message Schemas
+# Message schemas
 
-JSON Schema definitions (draft 2020-12) for the neoirc protocol. Messages use
-**IRC command names and numeric reply codes** (RFC 1459/2812) encoded as JSON
-over HTTP.
+This directory holds JSON Schema files (draft 2020-12) for the messages that the
+neoirc HTTP API carries. `message.json` describes the envelope every message
+uses. `commands/` holds one file per IRC command and `numerics/` one file per
+numeric reply. `README.md` at the repository root documents every command, reply
+and field.
 
-## Envelope
+## The envelope
 
-Every message is a JSON object with a `command` field. The format maps directly
-to IRC wire format:
+Every message is one JSON object with these fields:
+
+- `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, assigned by the server.
+- `from`: the sender's nick, or the server name on a server message.
+- `to`: the target: a channel name starting with `#`, or a nick.
+- `params`: further positional parameters, as an array of strings. `KICK` and
+  many numeric replies use it.
+- `body`: an array of strings, one per line of text. It is never a bare string.
+- `ts`: when the server stored the message, in RFC 3339 form, in UTC.
+- `meta`: an object of extra data, such as a hashcash stamp in `meta.hashcash`.
+  The server stores and relays it as it is.
+
+Two IRC lines and their JSON form:
 
 ```
-IRC:  :nick PRIVMSG #channel :hello world
-JSON: {"command": "PRIVMSG", "from": "nick", "to": "#channel", "body": ["hello world"]}
+IRC:  :alice PRIVMSG #general :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..."}}
+IRC:  :neoirc 353 alice = #general :@op1!op1@host1 alice!alice@host2
+JSON: {"command": "RPL_NAMREPLY", "code": 353, "from": "neoirc", "to": "alice",
+       "params": ["=", "#general"], "body": ["@op1!op1@host1 alice!alice@host2"]}
 ```
 
-Common fields (see `message.json` for full schema):
+A `body` with two strings is a two-line message:
 
-| Field     | Type            | Description                                          |
-| --------- | --------------- | ---------------------------------------------------- |
-| `id`      | string (uuid)   | Server-assigned message UUID                         |
-| `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.)       |
+```
+{"command": "PRIVMSG", "to": "#general", "body": ["line one", "line two"]}
+```
 
-**Structured bodies:** `body` is always an array of strings (for text) or an
-object (for structured data like PUBKEY). Never a raw string. This enables:
+## Files
 
-- Multiline messages without escape sequences
-- Deterministic canonicalization via RFC 8785 JCS for signing
-- Structured data where needed
+Commands, in `commands/`:
 
-## Commands
+- `PRIVMSG.json`: a message to a channel or a user.
+- `NOTICE.json`: a notice. A client must not answer a notice automatically.
+- `JOIN.json`: a user joined a channel.
+- `PART.json`: a user left a channel.
+- `QUIT.json`: a user left the server.
+- `NICK.json`: a user changed nick.
+- `TOPIC.json`: a channel topic was set.
+- `MODE.json`: a channel mode was changed.
+- `KICK.json`: a channel operator removed a user from a channel.
+- `PING.json` and `PONG.json`: keepalive.
+- `PUBKEY.json`: a public signing key announcement. The server does not have
+  this command and answers it with `ERR_UNKNOWNCOMMAND` (421).
 
-IRC commands used for client↔server and server↔server communication.
+Numeric replies, in `numerics/`:
 
-| Command   | File                    | RFC         | Description                |
-| --------- | ----------------------- | ----------- | -------------------------- |
-| `PRIVMSG` | `commands/PRIVMSG.json` | 1459 §4.4.1 | Message to channel or user |
-| `NOTICE`  | `commands/NOTICE.json`  | 1459 §4.4.2 | Notice (no auto-reply)     |
-| `JOIN`    | `commands/JOIN.json`    | 1459 §4.2.1 | Join a channel             |
-| `PART`    | `commands/PART.json`    | 1459 §4.2.2 | Leave a channel            |
-| `QUIT`    | `commands/QUIT.json`    | 1459 §4.1.6 | User disconnected          |
-| `NICK`    | `commands/NICK.json`    | 1459 §4.1.2 | Change nickname            |
-| `TOPIC`   | `commands/TOPIC.json`   | 1459 §4.2.4 | Get/set channel topic      |
-| `MODE`    | `commands/MODE.json`    | 1459 §4.2.3 | Set channel/user modes     |
-| `KICK`    | `commands/KICK.json`    | 1459 §4.2.8 | Kick user from channel     |
-| `PING`    | `commands/PING.json`    | 1459 §4.6.2 | Keepalive                  |
-| `PONG`    | `commands/PONG.json`    | 1459 §4.6.3 | Keepalive response         |
-| `PUBKEY`  | `commands/PUBKEY.json`  | (extension) | Announce/relay signing key |
+- `001.json` `RPL_WELCOME`, `002.json` `RPL_YOURHOST`, `003.json` `RPL_CREATED`
+  and `004.json` `RPL_MYINFO`: the welcome replies.
+- `322.json` `RPL_LIST` and `323.json` `RPL_LISTEND`: the channel list.
+- `332.json` `RPL_TOPIC`: a channel's topic.
+- `353.json` `RPL_NAMREPLY` and `366.json` `RPL_ENDOFNAMES`: a channel's member
+  list.
+- `372.json` `RPL_MOTD`, `375.json` `RPL_MOTDSTART` and `376.json`
+  `RPL_ENDOFMOTD`: the message of the day.
+- `401.json` `ERR_NOSUCHNICK`: no such nick.
+- `403.json` `ERR_NOSUCHCHANNEL`: no such channel.
+- `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.
 
-## Numeric Replies
+## Where the files differ from the server
 
-Three-digit codes for server responses, per IRC convention.
+Where a schema file and the server disagree, the server is right:
 
-### Success / Informational (0xx–3xx)
-
-| Code  | Name           | File                | Description                    |
-| ----- | -------------- | ------------------- | ------------------------------ |
-| `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)
-
-| Code  | Name                 | File                | Description             |
-| ----- | -------------------- | ------------------- | ----------------------- |
-| `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.
+- The numeric files put the three-digit code in `command` and have no `code`
+  field. The server puts the reply's name in `command` and its number in `code`.
+- `353.json` says `body` lists nicks. Over the HTTP API the server lists
+  hostmasks, such as `@op1!op1@host1`.
+- `MODE.json` puts the mode change in `params`. The server puts it in `body`:
+  one string such as `"+o bob"`, or the change and its value as two strings,
+  such as `"+k"` and `"secret"`.
+- `JOIN.json` has no `body`. The server's `JOIN` event repeats the channel name
+  in `body`.
+- `PING.json` describes a token in `body`. The server ignores the body of a
+  `PING` and answers the HTTP request itself with
+  `{"command": "PONG", "from": "<server name>"}`.
+- `TOPIC.json` says a `TOPIC` without a body queries the topic. Over the HTTP
+  API a `TOPIC` without a body gets `ERR_NEEDMOREPARAMS` (461).
+- `PUBKEY.json` describes a command the server does not have.