Rewrite README.md sentence by sentence (closes #327)

Rewrites README.md from scratch against the code on next, for
#327: what pixa is and how to
use it, deployment, design, the settings reference, then development
and testing. The Configuration list keeps one item per setting, as
TestReadmeNamesEverySetting reads it; the test is unchanged. The
statements where the old text disagreed with the code are listed in
the PR body.

Model: fable-5-1

AGENTS.md

@@ -1,76 +1,75 @@
 # Repository Rules
 
-Last Updated 2026-10-27
+Last Updated 2026-01-08
 
-These rules MUST be followed at all times. This is very important.
+These rules MUST be followed at all times, it is very important.
 
-- Never use `git add -A`. Stage specific changes for a deliberate commit. A
+- Never use `git add -A` - add specific changes to a deliberate commit. A commit
-  commit holds one change. After each change, make a commit with a good one-line
+  should contain one change. After each change, make a commit with a good
-  summary.
+  one-line summary.
 
 - NEVER modify the linter config without asking first.
 
-- NEVER modify a test to exclude special cases or otherwise make it pass without
+- NEVER modify tests to exclude special cases or otherwise get them to pass
-  asking first. In almost all cases, change the code, NOT the test. You need
+  without asking first. In almost all cases, the code should be changed, NOT the
-  explicit user approval to modify an existing test. If you think a test needs
+  tests. If you think the test needs to be changed, make your case for that and
-  to change, make your case and ask for permission to proceed. Then stop. A bug
+  ask for permission to proceed, then stop. You need explicit user approval to
-  fix may change an existing test without asking only when that test pins
+  modify existing tests. A bug fix may change an existing test without asking
-  exactly the behavior the filed bug calls wrong. The change must then move the
+  when that test pins exactly the behavior the filed bug calls wrong, and the
-  test to the fixed behavior and nothing else. Any other change to an existing
+  change moves it to the fixed behavior and nothing else; any other change to an
-  test needs explicit user approval. Writing NEW tests needs no approval.
+  existing test still needs explicit user approval. (You do not need user
+  approval for writing NEW tests.)
 
-- When linting, assume the linter config is CORRECT. Treat each item the linter
+- When linting, assume the linter config is CORRECT, and that each item output
-  reports as something that legitimately needs fixing in the code.
+  by the linter is something that legitimately needs fixing in the code.
 
 - When running tests, use `make test`.
 
-- Before committing, run `make check`. It runs `make test`, `make lint` and
+- Before commits, run `make check`. This runs `make lint` and `make test` and
-  `make fmt-check`. Any issue it finds MUST be resolved before committing,
+  `make check-fmt`. Any issues discovered MUST be resolved before committing
-  unless you are explicitly told otherwise.
+  unless explicitly told otherwise.
 
 - When fixing a bug, write a failing test for the bug FIRST. Add appropriate
-  logging to the test, to make sure the test is written correctly. Commit that.
+  logging to the test to ensure it is written correctly. Commit that. Then go
-  Then work on the fix until the test passes, without changing the test further.
+  about fixing the bug until the test passes (without modifying the test
-  Then commit the fix.
+  further). Then commit that.
 
-- When adding a new feature, do the same: write a test first (test-driven
+- When adding a new feature, do the same - implement a test first (TDD). It
-  development, TDD). The test does not need to be very complex. Commit the test,
+  doesn't have to be super complex. Commit the test, then commit the feature.
-  then commit the feature.
 
-- When adding a new feature, use a feature branch. The feature branch reaches
+- When adding a new feature, use a feature branch. When the feature is
-  `next` through a PR that passes review. It is merged only when the feature is
+  completely finished and the code is up to standards (passes `make check`) then
-  completely finished and the code is up to standards. The code is up to
+  and only then can the feature branch be merged into `main` and the branch
-  standards when it passes `make check`. The branch is deleted after the merge.
+  deleted.
-  Only the user merges `next` into `main`.
 
-- Write `godoc` comments for all exported types and functions as you go along.
+- Write godoc documentation comments for all exported types and functions as you
+  go along.
 
-- ALWAYS be consistent in naming. If you name something one way in one place,
+- ALWAYS be consistent in naming. If you name something one thing in one place,
-  use the EXACT SAME name in every other place.
+  name it the EXACT SAME THING in another place.
 
-- Be descriptive and specific in naming. `al` is bad; `SourceHostAllowlist` is
+- Be descriptive and specific in naming. `wl` is bad; `SourceHostWhitelist` is
   good. `ConnsPerHost` is bad; `MaxConnectionsPerHost` is good.
 
-- This is not prototype or teaching code. It is designed for production. Any
+- This is not prototype or teaching code - this is designed for production. Any
-  security issue (such as denial of service) or other web vulnerability is a P1
+  security issues (such as denial of service) or other web vulnerabilities are
-  bug. It must be added at the top of `TODO.md`.
+  P1 bugs and must be added to TODO.md at the top.
 
-- Do not stub an implementation unless you are specifically instructed to. This
+- As this is production code, no stubbing of implementations unless specifically
-  is production code, and we need working implementations.
+  instructed. We need working implementations.
 
 - NEVER silently fall back to a different setting when a user's parameter
-  explicitly specifies a value. For example, if a user requests `format=webp`
+  explicitly specifies a value. If a user requests format=webp and WebP encoding
-  and WebP encoding is not supported, return an error. Do NOT silently output
+  is not supported, return an error - do NOT silently output PNG instead. If a
-  PNG instead. If a user specifies `fit=invalid` and that fit mode does not
+  user specifies fit=invalid and that fit mode doesn't exist, return an error -
-  exist, return an error. Do NOT silently default to `cover`. A silent fallback
+  do NOT silently default to "cover". Silent fallbacks violate the principle of
-  violates the principle of least surprise and masks bugs. Defaults are
+  least surprise and mask bugs. The only acceptable defaults are for OMITTED
-  acceptable only for OMITTED parameters, never for INVALID explicit values.
+  parameters, never for INVALID explicit values.
 
-- Avoid vendoring dependencies unless specifically instructed to. NEVER commit
+- Avoid vendoring deps unless specifically instructed to. NEVER commit the
-  the `vendor/` directory. NEVER commit compiled binaries. If such a directory
+  vendor directory, NEVER commit compiled binaries. If these directories or
-  or file exists and `.gitignore` does not list it, add it to `.gitignore`.
+  files exist, add them to .gitignore (and commit the .gitignore) if they are
-  Commit that `.gitignore` change. Keep the entire git repository, history
+  not already in there. Keep the entire git repository (with history) small -
-  included, under 20 MiB. Go over 20 MiB only when you specifically must commit
+  under 20MiB, unless you specifically must commit larger files (e.g. test
-  a large file, such as a media file used as a test fixture. Only OUR source
+  fixture example media files). Only OUR source code and immediately supporting
-  code and its immediately supporting files, such as test examples, go into the
+  files (such as test examples) goes into the repo/history.
-  repository and its history.