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)

AGENTS.md

@@ -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.

internal/server/export_test.go

@@ -15,6 +15,12 @@ func NewTestSPAServer() *Server {
 	return srv
 }
 
+// Listener returns the listener the start hook bound for the
+// HTTP server.
+func (srv *Server) Listener() net.Listener {
+	return srv.listener
+}
+
 // ServeUntilShutdown runs serveUntilShutdown, which serves the
 // HTTP server on listener, and returns when it does.
 func (srv *Server) ServeUntilShutdown(listener net.Listener) {

internal/server/server.go

@@ -50,6 +50,7 @@ type Server struct {
 	sentryEnabled bool
 	log           *slog.Logger
 	httpServer    *http.Server
+	listener      net.Listener
 	router        *chi.Mux
 	params        Params
 	mw            *middleware.Middleware
@@ -179,6 +180,8 @@ func (srv *Server) startHTTP(ctx context.Context) error {
 		return fmt.Errorf("http listen: %w", err)
 	}
 
+	srv.listener = listener
+
 	srv.httpServer = &http.Server{ //nolint:exhaustruct // optional fields
 		Addr:           listenAddr,
 		ReadTimeout:    httpReadTimeout,

internal/server/server_test.go

@@ -8,6 +8,7 @@ import (
 	"fmt"
 	"net"
 	"net/http"
+	"strconv"
 	"strings"
 	"testing"
 	"time"
@@ -55,20 +56,12 @@ func TestStopWaitsForRequestInProgress(t *testing.T) {
 		t.Fatalf("create session: %v", err)
 	}
 
-	// The test cannot read the port the system gave the app, so
+	tcpAddr, ok := srv.Listener().Addr().(*net.TCPAddr)
-	// it serves the same HTTP server on a listener of its own.
+	if !ok {
-	var listenConfig net.ListenConfig
+		t.Fatalf("listener address %v is not TCP", srv.Listener().Addr())
-
-	listener, err := listenConfig.Listen(
-		t.Context(), "tcp", "127.0.0.1:0",
-	)
-	if err != nil {
-		t.Fatalf("listen: %v", err)
 	}
 
-	go srv.ServeUntilShutdown(listener)
+	addr := net.JoinHostPort("127.0.0.1", strconv.Itoa(tcpAddr.Port))
-
-	addr := listener.Addr().String()
 
 	statuses := make(chan int, 1)