Rewrite AGENTS.md sentence by sentence

Rewrite the agent rules from scratch, with one idea per sentence and every file name and command in backticks. Drop the rule that models embed `models.Base`, which no package has. Say that the linter keeps tests in external test packages, and that an `export_test.go` file gives them access to unexported code. Limit the rules on doc comments and blank imports to files outside the tests. State magic numbers as a preference, and correct the blank-line rule for `return`. State the branch workflow: pull requests target `next` and only the owner merges `next` into `main`. Record the three snake_case JSON tags the HTTP API keeps. Part of #190. Model: fable-5-1 (writing); opus-5-5 (rework)
2026-10-27 13:56:57 +00:00
4 changed files with 144 additions and 437 deletions
@@ -1,55 +1,73 @@
-# AGENTS.md — Rules for AI Agents
+# Rules for coding agents
-## Before Every Commit
+This file holds the rules for coding agents working in this repository.
 `CONVENTIONS.md` defines the architecture. `REPO_POLICIES.md` defines the
 repository standards. Both are copies of shared documents. Do not edit them
 here.
-1. **Format**: `make fmt`
+## Before every commit
 2. **Check**: `make check` — the tests and the linter, which run in Docker, and
   the format check: all passing, zero issues
-Never run `go test`, `golangci-lint` or `gofmt` directly; use the `make`
+1. Run `make fmt`.
-targets.
+2. Run `make check`. It runs the tests and the linter in Docker, then the format
   check. All three must pass with no findings.
-No commit lands on main with lint errors, test failures, or formatting issues.
+Never run `go test`, `golangci-lint` or `gofmt` directly. Use the `make` targets
 instead, such as `make test` and `make lint`.
-## Code Style
+## Branches and pull requests
- Follow CONVENTIONS.md exactly — it defines the architecture
+- Never commit to `main` or `next` directly. Every change is a pull request from
- All exported types, functions, methods, and vars must have doc comments
+  a feature branch into `next`.
- All packages must have a package doc comment
+- Only the owner merges `next` into `main`.
- JSON tags use camelCase (not snake_case)
+- A pull request that closes an issue has the title `Description (closes #N)`.
- No magic numbers — use named constants
+- One logical change per commit.
- No inline error handling (`if err := ...; err != nil`) — use plain assignment
+- Commit messages are in the imperative mood and short.
 - Blank line before every `return` statement
 - Blank line separating embedded fields from regular fields in structs
 - Blank imports must have a justification comment
-## Git Workflow
+## Code style
- **Never commit directly to main** — all changes go on feature branches
+- Follow `CONVENTIONS.md`.
- Merge to main only when ready and passing all checks
+- Outside test files, every package has a package doc comment.
- PR titles: `Description (closes #N)` when closing an issue
+- Outside test files, every exported type, function and variable has a doc
- One logical change per commit
+  comment.
- Commit messages: imperative mood, concise
+- JSON tags are camelCase. The HTTP API's `last_id`, `pow_token` and
  `hashcash_bits` stay as they are, each with a `//nolint:tagliatelle` comment.
 - Prefer named constants to magic numbers. The `mnd` linter checks for them
  outside test files.
 - No inline error handling such as `if err := f(); err != nil`. Assign the error
  on its own line, then test it.
 - A `return` that follows another statement in its block has a blank line before
  it.
 - A blank line between the embedded fields of a struct and its other fields.
 - Outside test files, every blank import has a comment saying why it is there.
 ## Architecture
- Dependency injection via Uber fx — all components are fx providers
+- The server uses `go.uber.org/fx` for dependency injection.
- `internal/` for all application packages — one package per concern
+  `cmd/neoircd/main.go` lists its `fx` providers, such as `db.New` and
- Handlers return `http.HandlerFunc` using the closure pattern
+  `handlers.New`.
- Request/response structs defined inside handler closures
+- Application packages live under `internal/`, one package per concern.
- Models embed `models.Base` for database access to relation methods
+- `pkg/irc` holds the IRC command names and numeric reply codes.
- Database migrations in `internal/db/schema/` — embedded via `go:embed`
+- The `web` package embeds the built web client.
- SQLite by default (pure Go driver: modernc.org/sqlite)
+- Each exported `Handle…` method of `Handlers` returns an `http.HandlerFunc`.
 - A request struct is defined inside the method that decodes it.
 - The server uses the database only through the methods of `db.Database`.
 - The database migrations live in `internal/db/schema/` and are embedded with
  `go:embed`.
 - The database is SQLite, through the pure Go driver `modernc.org/sqlite`.
 ## Testing
- Table-driven tests preferred
+- Prefer table-driven tests.
- Use `testing.T` helpers, not assertion libraries
+- Use `testing.T` helpers, not assertion libraries.
- Test files live next to the code they test
+- A test file lives next to the code it tests and ends in `_test.go`.
- `_test.go` suffix, same package for white-box testing
+- The linter requires each test file to be in the package's external test
  package, such as `handlers_test`. It allows `export_test.go` and files ending
  in `_internal_test.go` in the package itself.
 - An `export_test.go` file gives the external tests access to the package's
  unexported code.
 ## Dependencies
- Required libraries are listed in CONVENTIONS.md §1
+- The required libraries are listed in `CONVENTIONS.md` §1.
- No new dependencies without justification
+- No new dependency without a reason given in the pull request.
- Pure Go preferred (no CGO)
+- Prefer dependencies written in pure Go, which build without cgo.
@@ -3,12 +3,8 @@ package config
 import (
 	"errors"
 	"fmt"
 	"log/slog"
 	"math"
 	"os"
 	"strconv"
 	"time"
 	"github.com/spf13/viper"
 	"go.uber.org/fx"
@@ -32,8 +28,6 @@ Type /help for available commands.`
 const DefaultDBURL = "file:///var/lib/neoirc/state.db" +
 	"?_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000)"
 var errOutOfRange = errors.New("setting out of range")
 // Params defines the dependencies for creating a Config.
 type Params struct {
 	fx.In
@@ -69,8 +63,6 @@ type Config struct {
 }
 // New creates a new Config by reading from files and environment variables.
 // It returns an error when a number, true/false or duration setting does
 // not parse or is out of range.
 func New(
 	_ fx.Lifecycle, params Params,
 ) (*Config, error) {
@@ -115,27 +107,29 @@ func New(
 	cfg := &Config{
 		DBURL:              viper.GetString("DBURL"),
 		Debug:              viper.GetBool("DEBUG"),
 		Port:               viper.GetInt("PORT"),
 		SentryDSN:          viper.GetString("SENTRY_DSN"),
 		MaintenanceMode:    viper.GetBool("MAINTENANCE_MODE"),
 		MetricsUsername:    viper.GetString("METRICS_USERNAME"),
 		MetricsPassword:    viper.GetString("METRICS_PASSWORD"),
 		MessageMaxAge:      viper.GetString("MESSAGE_MAX_AGE"),
 		MaxMessageSize:     viper.GetInt("MAX_MESSAGE_SIZE"),
 		QueueMaxAge:        viper.GetString("QUEUE_MAX_AGE"),
 		MOTD:               viper.GetString("MOTD"),
 		ServerName:         viper.GetString("SERVER_NAME"),
 		FederationKey:      viper.GetString("FEDERATION_KEY"),
 		SessionIdleTimeout: viper.GetString("SESSION_IDLE_TIMEOUT"),
 		HashcashBits:       viper.GetInt("NEOIRC_HASHCASH_BITS"),
 		OperName:           viper.GetString("NEOIRC_OPER_NAME"),
 		OperPassword:       viper.GetString("NEOIRC_OPER_PASSWORD"),
 		LoginRateLimit:     viper.GetFloat64("LOGIN_RATE_LIMIT"),
 		LoginRateBurst:     viper.GetInt("LOGIN_RATE_BURST"),
 		IRCListenAddr:      viper.GetString("IRC_LISTEN_ADDR"),
 		log:                log,
 		params:             &params,
 	}
 	err = parseSettings(cfg)
 	if err != nil {
 		return nil, err
 	}
 	// Viper counts an empty environment variable as unset, but an
 	// empty IRC_LISTEN_ADDR must turn the IRC listener off.
 	ircListenAddr, set := os.LookupEnv("IRC_LISTEN_ADDR")
@@ -150,93 +144,3 @@ func New(
 	return cfg, nil
 }
 // parseSettings reads the number and true/false settings into cfg and
 // checks the duration settings. Each number and duration must be above
 // zero. PORT and NEOIRC_HASHCASH_BITS may also be zero: port 0 lets the
 // system pick a port, and 0 bits turns proof of work off. The error
 // names each setting that does not parse or is out of range.
 func parseSettings(cfg *Config) error {
 	return errors.Join(
 		parseInt("PORT", 0, &cfg.Port),
 		parseInt("MAX_MESSAGE_SIZE", 1, &cfg.MaxMessageSize),
 		parseInt("NEOIRC_HASHCASH_BITS", 0, &cfg.HashcashBits),
 		parseInt("LOGIN_RATE_BURST", 1, &cfg.LoginRateBurst),
 		parseFloat("LOGIN_RATE_LIMIT", &cfg.LoginRateLimit),
 		parseBool("DEBUG", &cfg.Debug),
 		parseBool("MAINTENANCE_MODE", &cfg.MaintenanceMode),
 		checkDuration("MESSAGE_MAX_AGE", cfg.MessageMaxAge),
 		checkDuration("QUEUE_MAX_AGE", cfg.QueueMaxAge),
 		checkDuration("SESSION_IDLE_TIMEOUT", cfg.SessionIdleTimeout),
 	)
 }
 // parseInt sets *value to the setting key read as a whole number. It
 // returns an error when the value does not parse or is below minimum.
 func parseInt(key string, minimum int, value *int) error {
 	raw := viper.GetString(key)
 	parsed, err := strconv.Atoi(raw)
 	if err != nil {
 		return fmt.Errorf("cannot parse %s: %w", key, err)
 	}
 	if parsed < minimum {
 		return fmt.Errorf("%w: %s is %s, but must be at least %d",
 			errOutOfRange, key, raw, minimum)
 	}
 	*value = parsed
 	return nil
 }
 // parseFloat sets *value to the setting key read as a floating-point
 // number. It returns an error when the value does not parse or is not a
 // finite number above zero.
 func parseFloat(key string, value *float64) error {
 	raw := viper.GetString(key)
 	parsed, err := strconv.ParseFloat(raw, 64)
 	if err != nil {
 		return fmt.Errorf("cannot parse %s: %w", key, err)
 	}
 	if math.IsNaN(parsed) || math.IsInf(parsed, 0) || parsed <= 0 {
 		return fmt.Errorf(
 			"%w: %s is %s, but must be a finite number above zero",
 			errOutOfRange, key, raw)
 	}
 	*value = parsed
 	return nil
 }
 // parseBool sets *value to the setting key read as true or false.
 func parseBool(key string, value *bool) error {
 	parsed, err := strconv.ParseBool(viper.GetString(key))
 	if err != nil {
 		return fmt.Errorf("cannot parse %s: %w", key, err)
 	}
 	*value = parsed
 	return nil
 }
 // checkDuration returns an error naming the setting key when value is
 // not a Go duration above zero.
 func checkDuration(key, value string) error {
 	duration, err := time.ParseDuration(value)
 	if err != nil {
 		return fmt.Errorf("cannot parse %s: %w", key, err)
 	}
 	if duration <= 0 {
 		return fmt.Errorf("%w: %s is %s, but must be above zero",
 			errOutOfRange, key, value)
 	}
 	return nil
 }
@@ -2,7 +2,6 @@ package config_test
 import (
 	"os"
 	"strings"
 	"testing"
 	"time"
@@ -11,8 +10,7 @@ import (
 	"sneak.berlin/go/neoirc/internal/logger"
 )
-// loadConfig runs config.New and returns its result.
+func newConfig(t *testing.T) *config.Config {
 func loadConfig(t *testing.T) (*config.Config, error) {
 	t.Helper()
 	globs := &globals.Globals{
@@ -26,15 +24,9 @@ func loadConfig(t *testing.T) (*config.Config, error) {
 		t.Fatal(err)
 	}
-	return config.New(
+	cfg, err := config.New(
 		nil, config.Params{Globals: globs, Logger: log},
 	)
 }
 func newConfig(t *testing.T) *config.Config {
 	t.Helper()
 	cfg, err := loadConfig(t)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -42,145 +34,6 @@ func newConfig(t *testing.T) *config.Config {
 	return cfg
 }
 func TestUnsetSettingsKeepDefaults(t *testing.T) {
 	// Viper counts an empty environment variable as unset.
 	t.Setenv("PORT", "")
 	t.Setenv("MAX_MESSAGE_SIZE", "")
 	t.Setenv("NEOIRC_HASHCASH_BITS", "")
 	t.Setenv("LOGIN_RATE_BURST", "")
 	t.Setenv("LOGIN_RATE_LIMIT", "")
 	t.Setenv("DEBUG", "")
 	t.Setenv("MAINTENANCE_MODE", "")
 	t.Setenv("MESSAGE_MAX_AGE", "")
 	t.Setenv("QUEUE_MAX_AGE", "")
 	t.Setenv("SESSION_IDLE_TIMEOUT", "")
 	// Each duration setting defaults to 30 days.
 	const thirtyDays = "720h"
 	want := settings{
 		Port:               8080,
 		MaxMessageSize:     4096,
 		HashcashBits:       20,
 		LoginRateBurst:     5,
 		LoginRateLimit:     1,
 		Debug:              false,
 		MaintenanceMode:    false,
 		MessageMaxAge:      thirtyDays,
 		QueueMaxAge:        thirtyDays,
 		SessionIdleTimeout: thirtyDays,
 	}
 	got := settingsOf(newConfig(t))
 	if got != want {
 		t.Errorf("settings = %+v, want %+v", got, want)
 	}
 }
 func TestValidSettingsAreUsed(t *testing.T) {
 	// Each whole number is the lowest value its setting allows, and 1ns
 	// is the shortest duration allowed.
 	t.Setenv("PORT", "0")
 	t.Setenv("MAX_MESSAGE_SIZE", "1")
 	t.Setenv("NEOIRC_HASHCASH_BITS", "0")
 	t.Setenv("LOGIN_RATE_BURST", "1")
 	t.Setenv("LOGIN_RATE_LIMIT", "0.5")
 	t.Setenv("DEBUG", "true")
 	t.Setenv("MAINTENANCE_MODE", "true")
 	t.Setenv("MESSAGE_MAX_AGE", "1ns")
 	t.Setenv("QUEUE_MAX_AGE", "1h30m")
 	t.Setenv("SESSION_IDLE_TIMEOUT", "45m")
 	want := settings{
 		Port:               0,
 		MaxMessageSize:     1,
 		HashcashBits:       0,
 		LoginRateBurst:     1,
 		LoginRateLimit:     0.5,
 		Debug:              true,
 		MaintenanceMode:    true,
 		MessageMaxAge:      "1ns",
 		QueueMaxAge:        "1h30m",
 		SessionIdleTimeout: "45m",
 	}
 	got := settingsOf(newConfig(t))
 	if got != want {
 		t.Errorf("settings = %+v, want %+v", got, want)
 	}
 }
 // settings holds the Config fields whose settings config.New parses.
 type settings struct {
 	Port               int
 	MaxMessageSize     int
 	HashcashBits       int
 	LoginRateBurst     int
 	LoginRateLimit     float64
 	Debug              bool
 	MaintenanceMode    bool
 	MessageMaxAge      string
 	QueueMaxAge        string
 	SessionIdleTimeout string
 }
 func settingsOf(cfg *config.Config) settings {
 	return settings{
 		Port:               cfg.Port,
 		MaxMessageSize:     cfg.MaxMessageSize,
 		HashcashBits:       cfg.HashcashBits,
 		LoginRateBurst:     cfg.LoginRateBurst,
 		LoginRateLimit:     cfg.LoginRateLimit,
 		Debug:              cfg.Debug,
 		MaintenanceMode:    cfg.MaintenanceMode,
 		MessageMaxAge:      cfg.MessageMaxAge,
 		QueueMaxAge:        cfg.QueueMaxAge,
 		SessionIdleTimeout: cfg.SessionIdleTimeout,
 	}
 }
 func TestBadSettingStopsStartup(t *testing.T) {
 	// For each setting, the first value does not parse and the others
 	// parse but are out of range.
 	tests := []struct {
 		key    string
 		values []string
 	}{
 		{key: "PORT", values: []string{"80a", "-1"}},
 		{key: "MAX_MESSAGE_SIZE", values: []string{"4k", "0", "-4096"}},
 		{key: "NEOIRC_HASHCASH_BITS", values: []string{"twenty", "-1"}},
 		{key: "LOGIN_RATE_BURST", values: []string{"five", "0", "-5"}},
 		{key: "LOGIN_RATE_LIMIT", values: []string{
 			"fast", "0", "-1", "NaN", "Inf", "-Inf",
 		}},
 		{key: "DEBUG", values: []string{"yes"}},
 		{key: "MAINTENANCE_MODE", values: []string{"on"}},
 		{key: "MESSAGE_MAX_AGE", values: []string{"30d", "0", "-1h"}},
 		{key: "QUEUE_MAX_AGE", values: []string{"720", "0s", "-24h"}},
 		{key: "SESSION_IDLE_TIMEOUT", values: []string{"a month", "0", "-1m"}},
 	}
 	for _, test := range tests {
 		for _, value := range test.values {
 			t.Run(test.key+"="+value, func(t *testing.T) {
 				t.Setenv(test.key, value)
 				_, err := loadConfig(t)
 				if err == nil {
 					t.Fatalf("%s=%q: got no error", test.key, value)
 				}
 				msg := err.Error()
 				if !strings.Contains(msg, test.key) ||
 					!strings.Contains(msg, value) {
 					t.Errorf("error %q does not name %s and %q",
 						msg, test.key, value)
 				}
 			})
 		}
 	}
 }
 func TestIRCListenAddrUnsetKeepsDefault(t *testing.T) {
 	// t.Setenv puts back whatever value was there after the test.
 	t.Setenv("IRC_LISTEN_ADDR", "")
@@ -1,166 +1,98 @@
-# Message schemas
+# Message Schemas
-This directory holds JSON Schema files (draft 2020-12) for the messages that the
+JSON Schema definitions (draft 2020-12) for the neoirc protocol. Messages use
-neoirc HTTP API carries. `message.json` describes the fields that every message
+**IRC command names and numeric reply codes** (RFC 1459/2812) encoded as JSON
-can have. `commands/` has files for some commands. `numerics/` has files for
+over HTTP.
 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.
-The server can also run an IRC listener for ordinary IRC clients. The IRC
+## Envelope
 listener sends plain IRC lines, which these files do not describe.
-## Message fields
+Every message is a JSON object with a `command` field. The format maps directly
-
+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:  :alice!alice@* PRIVMSG #general :hello world
+IRC:  :nick PRIVMSG #channel :hello world
-JSON: {"command": "PRIVMSG", "from": "alice", "to": "#general", "body": ["hello world"]}
+JSON: {"command": "PRIVMSG", "from": "nick", "to": "#channel", "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..."}}
 ```
-In the JSON, a numeric reply has its name in `command` and its number in `code`.
+Common fields (see `message.json` for full schema):
 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",
+| --------- | --------------- | ---------------------------------------------------- |
- "params": ["=", "#general"], "body": ["@op1!op1@host1 alice!alice@host2"]}
+| `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.)       |
-A `PRIVMSG` whose `body` has two strings is a two-line message:
+**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:
-```
+- Multiline messages without escape sequences
-{"command": "PRIVMSG", "to": "#general", "body": ["line one", "line two"]}
+- Deterministic canonicalization via RFC 8785 JCS for signing
-```
+- Structured data where needed
-## Files
+## Commands
-Commands, in `commands/`:
+IRC commands used for client↔server and server↔server communication.
- `PRIVMSG.json`: a message to a channel or a user.
+| Command   | File                    | RFC         | Description                |
- `NOTICE.json`: a notice, which is a message that a client must not answer
+| --------- | ----------------------- | ----------- | -------------------------- |
-  automatically.
+| `PRIVMSG` | `commands/PRIVMSG.json` | 1459 §4.4.1 | Message to channel or user |
- `JOIN.json`: a user joined a channel.
+| `NOTICE`  | `commands/NOTICE.json`  | 1459 §4.4.2 | Notice (no auto-reply)     |
- `PART.json`: a user left a channel.
+| `JOIN`    | `commands/JOIN.json`    | 1459 §4.2.1 | Join a channel             |
- `QUIT.json`: a user left the server.
+| `PART`    | `commands/PART.json`    | 1459 §4.2.2 | Leave a channel            |
- `NICK.json`: a user changed nick.
+| `QUIT`    | `commands/QUIT.json`    | 1459 §4.1.6 | User disconnected          |
- `TOPIC.json`: a channel topic was set.
+| `NICK`    | `commands/NICK.json`    | 1459 §4.1.2 | Change nickname            |
- `MODE.json`: a channel mode was changed.
+| `TOPIC`   | `commands/TOPIC.json`   | 1459 §4.2.4 | Get/set channel topic      |
- `KICK.json`: a channel operator removed a user from a channel.
+| `MODE`    | `commands/MODE.json`    | 1459 §4.2.3 | Set channel/user modes     |
- `PING.json`: a check that the server still answers.
+| `KICK`    | `commands/KICK.json`    | 1459 §4.2.8 | Kick user from channel     |
- `PONG.json`: the answer to a `PING`.
+| `PING`    | `commands/PING.json`    | 1459 §4.6.2 | Keepalive                  |
- `PUBKEY.json`: an announcement of a user's public signing key. The server has
+| `PONG`    | `commands/PONG.json`    | 1459 §4.6.3 | Keepalive response         |
-  no such command. It answers a `PUBKEY` with `ERR_UNKNOWNCOMMAND` (`421`).
+| `PUBKEY`  | `commands/PUBKEY.json`  | (extension) | Announce/relay signing key |
-Numeric replies, in `numerics/`:
+## Numeric Replies
- `001.json`: `RPL_WELCOME`, which welcomes a new user.
+Three-digit codes for server responses, per IRC convention.
 - `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.
-## Where the files differ from the HTTP API
+### Success / Informational (0xx–3xx)
-Where a schema file and the HTTP API disagree, the HTTP API is right:
+| 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                    |
- `message.json` and the files in `numerics/` put the three-digit code in
+### Errors (4xx)
  `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`.
-The HTTP API also accepts some messages that the files do not allow, such as a
+| Code  | Name                 | File                | Description             |
-`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.