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 the schema files disagree with the server,
compared file by file with the HTTP API, so a reader is not misled; the
files themselves are unchanged.

Part of #190.

Model: fable-5-1 (writing); opus-5-5 (rework)

schema/README.md

@@ -2,13 +2,13 @@
 
 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.
+uses. `commands/` has files for some of the IRC commands. `numerics/` has files
+for some of the numeric replies. `README.md` at the repository root documents
+the protocol.
 
 ## The envelope
 
-Every message is one JSON object with these fields:
+Every message is one JSON object. 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.
@@ -16,23 +16,34 @@ Every message is one JSON object with these fields:
   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.
+- `to`: the target, such as a channel name starting with `#` or a nick.
+- `params`: other parameters, in order, as an array of strings. `KICK` events
+  and many numeric replies have it. The server 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`: when the server stored the message, as 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`.
-  The server stores and relays it as it is.
+  A hashcash stamp is a short string that takes a computer some work to make. A
+  channel with mode `+H` needs one in every `PRIVMSG`. The server relays the
+  `meta` of a `PRIVMSG` or `NOTICE` unchanged. It drops the `meta` of every
+  other command.
 
-Two IRC lines and their JSON form:
+A `PRIVMSG` as the IRC listener sends it, and as the HTTP API sends it without
+`id`, `ts` and `meta`:
 
 ```
-IRC:  :alice PRIVMSG #general :hello world
+IRC:  :alice!alice@* PRIVMSG #general :hello world
 JSON: {"command": "PRIVMSG", "from": "alice", "to": "#general", "body": ["hello world"]}
+```
 
-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"]}
+A numeric reply has its name in `command` and its number in `code`. This `353`
+reply lists the members of `#general`, again without `id`, `ts` and `meta`:
+
+```
+{"command": "RPL_NAMREPLY", "code": 353, "from": "neoirc", "to": "alice",
+ "params": ["=", "#general"], "body": ["@op1!op1@host1 alice!alice@host2"]}
 ```
 
 A `body` with two strings is a two-line message:
@@ -54,42 +65,92 @@ Commands, in `commands/`:
 - `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).
+- `PING.json`: a check that the server still answers.
+- `PONG.json`: the answer to a `PING`.
+- `PUBKEY.json`: an announcement of a user's public signing key. The server has
+  no such command. It answers a `PUBKEY` with `ERR_UNKNOWNCOMMAND` (421).
 
 Numeric replies, in `numerics/`:
 
-- `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.
+- `001.json`: `RPL_WELCOME`, which welcomes a new user.
+- `002.json`: `RPL_YOURHOST`, the server's name and version.
+- `003.json`: `RPL_CREATED`, the date the server started.
+- `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.
 
 ## Where the files differ from the server
 
 Where a schema file and the server disagree, the server is right:
 
-- 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
+- `message.json` and 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`.
+- `message.json` allows an object as `body`. The server reads only arrays of
+  strings. A `PRIVMSG` with an object 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 server keeps `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 server 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 server's `JOIN` event repeats the channel name
+  there.
+- `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 server reads a client's
+  `KICK` from `body`: the nick, then an optional reason.
+- `MODE.json` puts the mode change in `params`. The server uses `body` instead.
+  A client sends the change and any value as separate strings, such as `"+o"`
+  and `"bob"`. The server's `MODE` event has one string such as `"+o bob"`, or
+  the change and its value as two strings, such as `"+k"` and `"secret"`.
+- `NOTICE.json` allows `*` as `to`. The server answers that 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
+  server ignores the `body` of a `PING`. It 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).
+- `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 only the server sends `QUIT`. A client can send it too, to
+  end its session. The client's `QUIT` can carry a reason in `body`.
+- `TOPIC.json` says a `TOPIC` without a `body` queries the topic. Over the HTTP
+  API a `TOPIC` without a `body` gets `ERR_NEEDMOREPARAMS` (461).
+- `TOPIC.json` says an empty array clears the topic. The server answers `[]`
+  with `ERR_NEEDMOREPARAMS` (461). A `body` of `[""]` clears the topic.
+- `003.json` describes the server's creation date. The server sends the date it
+  last started.
+- `004.json` has example mode lists. The server 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 each
+  secret channel that the user is not on.
+- `353.json` says `body` lists nicks. Over the HTTP API the server 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 server adds a full
+  stop.
+- `401.json` gives the text as `No such nick/channel`. For a `PRIVMSG` or
+  `NOTICE` to an unknown nick, the server sends `No such nick`.
+- `433.json` has an example with `*` as `to`. Over the HTTP API the server sends
+  `433` only in answer to a `NICK`, with the user's nick as `to`.
+
+The server also accepts some messages that the files do not allow, such as a
+channel name without its `#`.