Split the README reference material into docs/

The README was 794 lines: the summary, the design rationale, the whole macro
reference, the threading contract, the build internals and the exit-status
specification in one file. It is now 178 lines -- summary, installation,
quickstart, and an index -- and the reference material lives in docs/, one file
per topic: architecture, usage, status-codes, uncaught-errors, exit-status,
thread-safety, building.

The prose moved as written. Inbound references followed it: UPGRADING.md,
TODO.md, include/akerror.tmpl.h and tests/err_threads_handoff.c now name the
docs/ file that owns the text they cite, and AGENTS.md says where new
documentation goes so the README does not grow back.

Five factual errors fixed in the moved text:

- Both NULL-pointer examples inverted their test. FAIL_ZERO_* fails when the
  expression is zero, so `(somePointer == NULL)` failed on a *valid* pointer.
  They now read `(somePointer != NULL)`.
- AKERROR_NOIGNORE, four times including the #define, is AKERR_NOIGNORE.
- FINISH_NORExbTURN is FINISH_NORETURN.
- "functiions" is "functions".
- The architecture link pointed at include/akerror.h, which is generated and
  not in the tree; it points at include/akerror.tmpl.h.

The quickstart is new text. It compiles under -Wall -Wextra -Werror and was run
through all three of its paths: handled usage error exits 0, unhandled IO error
prints a trace and exits with the status, success exits 0.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/building.md

@@ -0,0 +1,61 @@
+# Building libakerror
+
+The ordinary build is an out-of-tree CMake build, described in
+[the README](../README.md#installation). This file covers what the build
+generates for you, what it links against, and the configure options that change
+either of those.
+
+## Configure options
+
+| Option | Default | What it does |
+| ------ | ------- | ------------ |
+| `AKERR_THREADS` | `auto` | Threading backend: `auto`, `pthread`, or `none`. `auto` takes POSIX threads and **fails the configure** if it cannot find them. See [Building single threaded](thread-safety.md#building-single-threaded). |
+| `AKERR_USE_STDLIB` | `ON` | Link against the C standard library. See [Dependencies](#dependencies) for what you must supply instead when this is `OFF`. |
+| `AKERR_STATUS_NAME_SLOTS` | `4096` | Slots in the status-name table; 75% of it is usable. |
+| `AKERR_MAX_RESERVED_STATUS_RANGES` | `64` | How many status ranges may be reserved in one process. |
+| `AKERR_SANITIZE` | *(empty)* | Sanitizer list applied to the library and the tests, e.g. `thread` or `address,undefined`. |
+| `AKERR_COVERAGE` | `OFF` | Instrument the library with gcov counters. |
+
+The two capacity options are applied `PRIVATE`: the tables live entirely in
+`src/error.c`, so raising them never changes anything a consumer can see. See
+[UPGRADING.md](../UPGRADING.md) for what happens when you exhaust them.
+
+## Templating and autogenerated code
+
+The build process relies upon `scripts/generrno.sh` which performs the following:
+
+1. Executes `errno --list` and gathers up the output
+1. Templates `include/akerror.tmpl.h` into `include/akerror.h` to set the `AKERR_LAST_ERRNO_VALUE` equal to the highest integer defined by `errno`
+2. Generates `src/errno.c` which contains a function called by `akerr_init` which initializes all of the status names for the previously defined values of `errno`.
+
+Neither output is meant to be edited. Change the template or the generator.
+
+## Dependencies
+
+This library depends upon `stdlib`, and upon POSIX threads unless it is built
+with `-DAKERR_THREADS=none` (see [Thread safety](thread-safety.md)). If you don't want to link against stdlib, you must modify the library code to include headers and link against a library that provides the following:
+
+- `memset` function
+- `strncpy` function
+- `strlen` function
+- `strcmp` function
+- `sprintf` function
+- `exit` function
+- `bool` type
+- `NULL` type
+- `INT_MAX` constant
+- `PATH_MAX` constant
+
+... then you can compile it thusly:
+
+```
+cmake -S . -B build -DAKERR_USE_STDLIB=OFF
+cmake --build build
+cmake --install build
+```
+
+**Known defect:** that configuration does not currently compile. `bool`,
+`PATH_MAX` and `NULL` are used unconditionally but only included under the
+stdlib branch, so the header's includes need untangling before
+`-DAKERR_USE_STDLIB=OFF` builds. The list above still states what a replacement
+must provide. See [TODO.md](../TODO.md).