Rewrite AGENTS.md sentence by sentence

Rewrite the agent rules from scratch, as a newcomer would read them,
with one idea per sentence and every file name and command in
backticks. Drop the rule that models embed `models.Base`, which no
package in the repository has, and the statement that tests share
their package. Nearly every test is in an external test package.
Where a test needs an unexported name, an `export_test.go` file in
the package exposes it. State the branch workflow in use: 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)

AGENTS.md

@@ -1,9 +1,8 @@
 # Rules for coding agents
 
-This file holds the rules for coding agents working in this repository.
+Rules for coding agents working in this repository. `CONVENTIONS.md` defines the
-`CONVENTIONS.md` defines the architecture. `REPO_POLICIES.md` defines the
+architecture and `REPO_POLICIES.md` the repository standards. Both are copies of
-repository standards. Both are copies of shared documents. Do not edit them
+shared documents and are not edited here.
-here.
 
 ## Before every commit
 
@@ -11,8 +10,8 @@ here.
 2. Run `make check`. It runs the tests and the linter in Docker, then the format
    check. All three must pass with no findings.
 
-Never run `go test`, `golangci-lint` or `gofmt` directly. Use the `make` targets
+Never run `go test`, `golangci-lint` or `gofmt` directly. The scripts in
-instead, such as `make test` and `make lint`.
+`script/` hold the flags and the Docker setup.
 
 ## Branches and pull requests
 
@@ -26,31 +25,26 @@ instead, such as `make test` and `make lint`.
 ## Code style
 
 - Follow `CONVENTIONS.md`.
-- Outside test files, every package has a package doc comment.
+- Every package has a package doc comment. Every exported type, function, method
-- Outside test files, every exported type, function and variable has a doc
+  and variable has a doc comment.
-  comment.
 - 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
+- No magic numbers. Use named constants.
-  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
+- A blank line before every `return`.
-  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.
+- Every blank import has a comment saying why it is there.
 
 ## Architecture
 
-- The server uses `go.uber.org/fx` for dependency injection.
+- The server uses `go.uber.org/fx` for dependency injection. Each of its
-  `cmd/neoircd/main.go` lists its `fx` providers, such as `db.New` and
+  components is an `fx` provider, wired together in `cmd/neoircd/main.go`.
-  `handlers.New`.
 - Application packages live under `internal/`, one package per concern.
-- `pkg/irc` holds the IRC command names and numeric reply codes.
+  `pkg/irc` holds the IRC command names and numeric reply codes.
-- The `web` package embeds the built web client.
+- A handler method returns an `http.HandlerFunc`.
-- Each exported `Handle…` method of `Handlers` returns an `http.HandlerFunc`.
+- A request struct is defined inside the handler that decodes it.
-- A request struct is defined inside the method that decodes it.
+- Database access goes through the methods of `db.Database`.
-- 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`.
@@ -60,11 +54,9 @@ instead, such as `make test` and `make lint`.
 - Prefer table-driven tests.
 - Use `testing.T` helpers, not assertion libraries.
 - A test file lives next to the code it tests and ends in `_test.go`.
-- The linter requires each test file to be in the package's external test
+- Tests are in the package's external test package, such as `handlers_test`.
-  package, such as `handlers_test`. It allows `export_test.go` and files ending
+  When a test needs an unexported name, an `export_test.go` file in the package
-  in `_internal_test.go` in the package itself.
+  exposes it.
-- An `export_test.go` file gives the external tests access to the package's
-  unexported code.
 
 ## Dependencies