libakgl/plan.md

Write the libakgl manual

Context

libakgl 0.7.0 exports 156 akgl_* functions across 20 public headers, and the only user-facing documentation is a 404-line README.md written as a FAQ. Half of it is developer process (git hooks, mutation testing, perf suites, memcheck) rather than anything a person building a game needs, and the half that is user-facing does not compile:

• PASS(e, akgl_heap_next_spritesheet(&sheet); — unbalanced parentheses, twice.
• sprite->frameids = [0, 1, 2, 3]; — not C in any dialect.
• myactor->state = 9AKGL_ACTOR_STATE_ALIVE | AKGL_ACTOR_STATE_FACE_LEFT); — a stray 9.
• strncpy((char *)&game.name, "sdl3-gametest", 256); — the exact call AGENTS.md forbids under Copying Into Fixed-Width Fields, in the first snippet a reader sees.
• int screenwidth = NULL;

The prose has drifted the same way, and two claims were confirmed false against src/:

• physics.h:195 says akgl_game_init passes the physics.engine property to akgl_physics_factory. akgl_game_init never calls the factory, and the string physics.engine appears nowhere in src/.
• registry.h:54 says akgl_registry_init creates the registries. akgl_game_init calls the eight individual initializers and never calls akgl_registry_init at all.

util/assets/littleguy.json — the sample data for the one shipped demo — still uses the pre-prefix state names ("ACTOR_STATE_ALIVE") and velocity_x, neither of which the current loader accepts.

This is not a reader routing around typos. It is what happens to samples and prose that nothing executes, and AGENTS.md already makes the argument in another context — "A test that has not failed has not been tested", "Do not trust a comment, a TODO entry, or a CI exclusion that states a premise." The sibling akbasic repository solved exactly this: every example in its manual is compiled or run by CTest, and a chapter that drifts from the code turns a job red.

The outcome wanted: a docs/ manual — introduction, design philosophy, a chapter per subsystem, and two tutorials building a complete 2D sidescroller and a complete top-down JRPG — with akbasic's harness ported so no sample in it can rot.

Decisions taken

Question	Answer
Tutorial assets	Vendor a curated Kenney.nl CC0 subset, with LICENSE, a provenance manifest, and a refresh script
Tutorial code	Real compiling, runnable targets under examples/, built by default and in CI
Existing README.md	Split: the FAQ half seeds docs/ (corrected); the developer-process half stays
Known defects	Documented inline in the owning chapter, cross-referenced to TODO.md

---

The governing editorial rule: reference upstream, do not restate it

This manual documents libakgl. It does not re-document its dependencies.

libakgl sits on libakerror, libakstdlib, SDL3, SDL3_image, SDL3_mixer, SDL3_ttf, jansson and the Tiled map format. Every one of those is documented by its own project, by people who own the code. A chapter that restates the ATTEMPT/CLEANUP/PROCESS/HANDLE/ FINISH protocol is a chapter that will be wrong the day libakerror changes it, and nothing in this repository's test suite would notice — the drift this whole project exists to fix, reintroduced from a different direction.

So each chapter answers exactly two questions and links out for the rest:

1. What does libakgl add or constrain here?
2. What does a libakgl caller actually write? — a small, harness-verified example.

Topic	Owned upstream — link, do not restate	What this manual owes the reader
ATTEMPT/CLEANUP/PROCESS/HANDLE/FINISH, PASS, CATCH, IGNORE	deps/libakerror	The status-code tables below; akgl_error_init() ordering; libakgl's own hazards
aksl_strncpy, aksl_fclose, aksl_atoi and friends	deps/libakstdlib	Which ones libakgl requires you to use, and why (AGENTS.md already argues it)
SDL_Renderer, SDL_Texture, events, SDL_PropertiesID	SDL3 wiki	The backend vtable, the frame contract, what libakgl does to the renderer's state
Audio decoding, MIX_Audio, mixers and tracks	SDL3_mixer	akgl_load_start_bgm, the track table, the separate three-voice synthesizer (ours)
TTF rasterizing and metrics	SDL3_ttf	The font registry, the teardown ordering trap, the rasterize-per-call cost
The TMJ map format, layers, tilesets, custom properties	Tiled documentation	libakgl's extensions and limits — actor objects, physics.model, the perspective band, AKGL_TILEMAP_MAX_*
json_t, json_decref, the jansson API	jansson manual	akgl_get_json_* — which status means "absent" vs "wrong type", and the borrowed-reference rule

Chapter 04 is the sharpest case. It does not teach the error protocol; it says "the protocol is libakerror's and is documented there", then spends its length on the three things that are genuinely libakgl's: the status-code tables, the libakgl-specific traps, and one worked example of a real libakgl call sequence.

One more decision, forced by what the exploration found

docs/ is a narrative manual, not a second reference. Every header already carries a substantial @file/@brief block explaining the subsystem's design rationale, and Doxyfile sets WARN_IF_UNDOCUMENTED = YES with WARN_AS_ERROR = FAIL_ON_WARNINGS, so an undocumented symbol already fails CI. The gap is navigation and worked examples, not reference text.

So the chapters teach a task and link to the generated Doxygen for per-function detail. They do not restate 156 signatures — a hand-copied signature table is exactly the artifact that drifts, and it would compete with a reference CI already keeps honest. Where a chapter genuinely needs a declaration or a constant table in front of the reader, it uses a ```c excerpt=include/akgl/heap.h block, so the text is the header.

---

The error-code tables

These are the exception to the rule above, and the reason the exception exists is concrete: libakerror documents the mechanism, but only libakgl can say which statuses its own 156 functions raise and what they mean here. A caller writing a HANDLE block needs that, and it is written down nowhere today. These tables are a required deliverable, not a nice-to-have.

Three tables, in chapter 04, with the appendix carrying the full cross-reference.

Corrected during execution. The tables below were written from header prose and were wrong in five places; the chapter as built carries the verified version. Recorded here because being wrong about the error codes, in the plan that exists to fix wrong documentation, is the joke writing itself.

• AKGL_ERR_LIMIT is not a status code. It is the one-past-the-end sentinel used to compute AKGL_ERR_COUNT (261). There are five codes, not six: AKGL_ERR_COUNT is 5, akgl_error_init names five, and tests/error.c asserts five.
• AKGL_ERR_REGISTRY is not raised by akgl_actor_set_character. One raise site in the library: src/controller.c:491. akgl_actor_initialize raises AKERR_KEY on a failed registry write; akgl_actor_set_character raises AKERR_NULLPOINTER.
• AKGL_ERR_BEHAVIOR is never raised by the library at all — only by tests/.
• akgl_get_json_with_default does default on AKERR_OUTOFBOUNDS (src/json_helpers.c:208, fixed in 0.5.0). The status it deliberately does not default on is AKERR_TYPE — a missing key can take a default, a malformed one cannot.
• Three statuses were missing: AKERR_TYPE (11 raise sites), AKERR_VALUE (8), AKERR_RELATIONSHIP (1). And AKERR_INDEX is never raised — it appears only as a HANDLE_GROUP arm.

Table 1 — libakgl's own status codes

All six are offsets from AKERR_FIRST_CONSUMER_STATUS, declared in include/akgl/error.h under owner string AKGL_ERR_OWNER ("libakgl"). The chapter renders this as an aligned table; the values come in as an excerpt=include/akgl/error.h block so the constants cannot drift from it.

Code	Value	Means	Typically raised by	What the caller does
AKGL_ERR_SDL	base + 0	An SDL call failed; the message carries SDL_GetError()	Anything touching a window, texture, renderer or mixer	Usually fatal at startup; check the driver and the asset path
AKGL_ERR_REGISTRY	base + 1	A name lookup or registration failed	akgl_actor_set_character, registry writes	Check the name and that the asset was loaded before the thing referencing it
AKGL_ERR_HEAP	base + 2	A pool is exhausted	every akgl_heap_next_*	Normally a missing release, not a small pool. Raise the AKGL_MAX_HEAP_* override only after checking
AKGL_ERR_BEHAVIOR	base + 3	A call was made in a state that forbids it	lifecycle and ordering violations	Fix the call order; see the startup sequence in chapter 07
AKGL_ERR_LOGICINTERRUPT	base + 4	Not a failure — a control signal. "Skip the rest of this tick for this actor"	your own movementlogicfunc	Raise it deliberately; akgl_physics_simulate swallows it. A backend's gravity/move must never raise it — there it aborts the whole step
AKGL_ERR_LIMIT	base + 5	A fixed compile-time bound was exceeded	loaders hitting AKGL_*_MAX_*	Reduce the asset, or raise the bound and rebuild everything linking libakgl

Table 2 — libakerror statuses libakgl raises, and what they mean here

The statuses themselves are libakerror's; their libakgl meaning is not documented anywhere. This table is what lets a caller write a HANDLE block with confidence.

Status	What it means when a libakgl function raises it
AKERR_NULLPOINTER	A required pointer argument was NULL, or a required field (akgl_game.name/.version/.uri) was empty. Also what akgl_text_rendertextat raises for an empty string — while akgl_text_measure accepts one
AKERR_KEY	A key is absent. The idiomatic "optional thing was not there" status: a missing JSON key, a character with no sprite for a state, a map with no properties. Frequently a HANDLE block rather than a failure
AKERR_INDEX	An array index was out of range
AKERR_OUTOFBOUNDS	A value did not fit its destination — aksl_strncpy truncation, a frame id past uint8_t, a flood fill past AKGL_DRAW_MAX_FLOOD_SPANS. Note: akgl_get_json_with_default does not default on this one, which is why it cannot currently give an array element a default
AKERR_IO	A read or write failed. Distinct from AKERR_EOF — that separation is the whole reason aksl_fgetc exists
AKERR_EOF	End of input. Sometimes the desired outcome, as in require_at_eof in src/game.c
AKERR_API	The function is not implemented. Currently akgl_physics_arcade_collide and akgl_render_2d_draw_mesh — both reached by ordinary-looking calls, so both get a chapter callout

Table 3 — the exit-status trap

Not a status list; a table because the failure is arithmetic and silent.

You write	Wait status the shell sees	Why
exit(AKGL_ERR_SDL)	0 — a clean run	An exit status is one byte; libakgl's band starts at 256
akerr_exit(status)	0→0, 1–255→itself, else 125	AKERR_EXIT_STATUS_UNREPRESENTABLE

Every suite in tests/ once reported success on the most common failure a library built on SDL can have. This belongs in the manual because a reader writing their own main will write the first line.

libakgl-specific traps that are ours to document

Not the protocol — the places libakgl makes the protocol bite in a way libakerror's docs cannot anticipate:

• akgl_error_init() must run before anything that can raise, or every libakgl error prints as "Unknown Error". akgl_game_init does it first; a host with its own startup path must too.
• akgl_registry_iterate_actor is an SDL callback returning void that ends in FINISH_NORETURN, so libakerror's default unhandled-error handler exits the process. A reader meets this the first time a sprite name is wrong.
• akgl_get_json_with_default hands back the context it was given when it does not handle the status, so a CLEANUP that also releases it double-releases and corrupts the failure instead of reporting it. AGENTS.md documents the correct shape; the chapter shows it as a verified example because a reader will hit it writing their first loader.
• libakerror ≥ 2.0.1 is a hard floor, enforced by two #error feature tests in include/akgl/error.h.
• akgl.pc names no dependencies at all — no Requires: — despite akerror.h being part of libakgl's public interface. Chapter 03 says so and gives the flags to add by hand. (TODO.md.)

---

Part 1 — The verification harness

Ported from akbasic/tests/docs_examples.sh (550 lines, bash + awk, no third-party deps). The c / excerpt / sh / output / norun / text machinery is generic and transfers directly; what drops out is everything about running an interpreter, and what gets added is the ability to link and run, because libakgl's samples are C rather than BASIC.

New file: tests/docs_examples.sh. Same contract, and these house conventions are worth copying verbatim rather than reinventing:

• Exit status is the number of failed examples; 2 for usage/setup errors.
• A fence with no info string is a hard error, and so is an unknown one. The failure mode the whole harness exists to prevent is passing because it quietly ran nothing.
• Paths forced absolute, because the script cds into sandboxes.
• An unreadable named document is exit 2 — akbasic learned this when an empty generator expression contributed an empty argument that replaced the entire document list, and the suite passed having checked nothing.
• A closing census line every run, treated as part of the result.
• FAIL <doc>:<line>: message on stderr; output mismatches diffed through cat -A, because the bugs it catches are trailing spaces and missing newlines.

Block kinds

Info string	What happens
```c	cc -fsyntax-only -std=gnu99 -Wall -Werror with the project include path
```c wrap=NAME	The same, wrapped in tests/docs_preludes/NAME.pre / .post
```c run=NAME	New. Compile, link against akgl, run headless; stdout compared to a following ```output block
```c excerpt=PATH	Must appear verbatim in PATH (comment- and whitespace-insensitive); not compiled
```c screenshot=NAME	New. Linked against the figure host; renders docs/images/NAME.png
```json kind=KIND	New. Loaded through the real loader: sprite, character, tilemap, properties
```output	Claimed by the preceding runnable block; an unclaimed one is a failure
```sh / sh norun	Run in a sandbox and must exit 0 / shown only
```cmake , ```text , norun	Never executed; counted as skipped, so the decision is explicit

-Werror on snippets, unlike the library: AGENTS.md keeps AKGL_WERROR off by default precisely because libakgl is consumed with add_subdirectory and a new compiler's diagnostic should not break someone else's build. A doc snippet is not a consumer, and a sample that warns is a sample that teaches the warning. gnu99 rather than c99, for akbasic's reason — akerror.h uses PATH_MAX, which <limits.h> hides under __STRICT_ANSI__.

#line directives are emitted before each body, so a diagnostic reads docs/14-physics.md:112: error: ... rather than pointing into a scratch file.

Three additions akbasic does not have

c run=NAME is the reason to do this at all for a game library. -fsyntax-only proves a call typechecks; it does not prove the startup order works, that a sprite loads, or that an ATTEMPT block releases what it acquired. A run block links a real binary and executes it under SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy SDL_RENDER_DRIVER=software — the same forcing scripts/memcheck.sh already uses. It asserts a clean exit and greps stderr for a raised context, because a libakgl program can fail and still exit 0.

json kind= exists because the asset formats are documented in prose and read by src/sprite.c, src/character.c, src/tilemap.c and src/registry.c, with nothing tying the two together. That gap is not hypothetical: util/assets/littleguy.json is already invalid against the loader it ships with. A small tools/docs_checkjson.c writes the block to a temp file and calls the matching akgl_*_load_json, so the documented format is the format the loader accepts.

c screenshot=NAME — tools/docs_screenshot.c supplies main, brings the library up headless at a stated size, calls the snippet's docs_frame(void), then SDL_RenderReadPixels and writes the PNG via SDL3_image. Copy two of akbasic's decisions exactly: any stdout during a render is a failure (an image of a blank screen is worse than no image), and --check compares and never repairs (a test that fixes what it measures passes the second time for the wrong reason).

Regeneration is cmake --build build --target docs_screenshots, never part of all. Figures are tracked, and docs/images/README.md says they are generated — the same tracked-generated-artifact contract AGENTS.md already spells out for SDL_GameControllerDB.h.

Support files and CMake wiring

tests/docs_examples.sh          the verifier
tests/docs_preludes/*.pre/.post akglbody, akglfile, akglapp, akglframe
tests/docs_setups/*.sh          asset fixtures a chapter should not have to show
tools/docs_checkjson.c          the json kind= validator
tools/docs_screenshot.c         the figure host
tools/docs_screenshots.sh       figure generation and --check
docs/images/                    tracked, generated

Include paths come from a file(GENERATE)'d docs_cflags.txt, so the transitive path through akerror, akstdlib, SDL3 and jansson has one source of truth. Register docs_examples and docs_screenshots with add_test, WORKING_DIRECTORY at the source root — and note CMakeLists.txt:76-102 shadows add_test only when top-level, so follow the file's existing idiom rather than calling the builtin.

Follow akbasic's CI decision: no docs-path filter. Documentation goes stale because the code moved, not because somebody edited a chapter.

A prelude must never let a wrong example compile. A prelude declaring akgl_game_init itself would defeat the check.

---

Part 2 — Chapter structure

docs/README.md is a hand-maintained two-column TOC, matching akbasic's conventions: NN-kebab-case.md, H1 repeating the ordinal, no front matter, H2/H3 only (no H4), relative links between chapters.

01-introduction.md	What libakgl is, what it refuses to be, the 0.03 ms frame budget from PERFORMANCE.md, and the dependency map — who owns which documentation
02-design-philosophy.md	Pools not malloc, backends not branches, errors that carry context, bit flags, name-based registries
03-getting-started.md	add_subdirectory vs akgl.pc (and the missing Requires:), the first window
04-errors.md	The three status tables above. Protocol referenced, not restated; libakgl's own traps; one worked call sequence
05-the-heap.md	The five pools, akgl_heap_next_*, akgl_String, the refcount asymmetry, AKGL_MAX_HEAP_* as an ABI constraint
06-the-registry.md	The eight registries, configuration properties, the id-0 silent-no-op, key truncation
07-the-game-and-the-frame.md	Startup order, akgl_game_update, the state lock, iterators, what savegames do and do not do
08-rendering.md	akgl_RenderBackend, the frame contract, cameras, and embedding via akgl_render_2d_bind
09-drawing.md	draw.h primitives, colour-as-argument, regions, flood fill's reentrancy limit
10-spritesheets-and-sprites.md	Sheet sharing by resolved path, the sprite JSON format, animation
11-characters.md	State→sprite mappings, speeds and accelerations, the character JSON format
12-actors.md	The 32-bit state mask, the six behaviour hooks, parents and children, layers
13-tilemaps.md	libakgl's Tiled extensions and limits — actor objects, physics.model, the perspective band. Format itself referenced
14-physics.md	thrust/environmental/velocity, null and arcade, what is not implemented
15-input.md	Control maps, push-not-poll dispatch, the keystroke ring, the gamepad DB
16-text-and-fonts.md	The font registry, measuring, the teardown ordering trap
17-audio.md	The three-voice synthesizer (ours, in full), and the SDL_mixer asset path (referenced)
18-utilities.md	Collision helpers, path resolution, akgl_get_json_* status semantics, static strings
19-tutorial-sidescroller.md	The first game, start to finish
20-tutorial-jrpg.md	The second game, start to finish
21-appendix-limits.md	Status cross-reference (which functions raise what), every AKGL_MAX_*, the full configuration property table

Chapter 04 precedes every subsystem because all 156 functions return akerr_ErrorContext AKERR_NOIGNORE *, and a reader who has not met the tables cannot read a single example. Chapter 08 carries the embedding seam as a first-class topic rather than a footnote — akgl_render_2d_bind is what akbasic actually consumes.

Constant tables (AKGL_MAX_HEAP_*, the actor state bits, the iterator ops, the status codes) go in as excerpt= blocks against their headers. Those headers hand-align their bit-flag tables, and scripts/reindent.el deliberately avoids tabify to preserve that alignment — an excerpt keeps the alignment and the values honest at once.

README.md keeps its developer-process half and gains a link to docs/. Its FAQ half is deleted, not copied: corrected content lives in the chapters, and one source of truth per topic is the entire point of the exercise.

---

Part 3 — The two tutorial games

Real targets: examples/sidescroller/ and examples/jrpg/, each a complete program, built by default and exercised in CI by a headless smoke run (run N frames, exit 0), so a tutorial cannot silently stop working.

The tutorial chapters quote these programs with ```c excerpt=examples/... blocks rather than restating the code. A chapter then cannot drift from a program that builds — the excerpt check fails the moment the source moves.

examples/sidescroller/ — gravity, a jump, platforms from a Tiled map, a coin pickup, a hazard. Exercises arcade physics, physics.gravity.y, AKGL_ACTOR_STATE_MOVING_*, tilemap layers, and a custom movementlogicfunc (which is where AKGL_ERR_LOGICINTERRUPT stops being a table row and becomes something the reader writes).

This game forces the chapter to make three honest statements, all from TODO.md:

• akgl_physics_arcade_collide is not implemented — it raises AKERR_API, and akgl_physics_simulate never calls collide at all. arcade_move does no clamping and consults no tilemap: an actor walks through a wall and off the edge of the world. The tutorial implements its own collision in movementlogicfunc and says exactly why.
• There is no terminal velocity. Gravity accumulates into ey unbounded — the physics sim reaches 560 px/s in 0.7 s and keeps going. physics.drag.y is the only brake (ey approaches gravity_y / drag_y) and is not documented as such anywhere today.
• Releasing a direction stops the actor dead. akgl_actor_cmhf_*_off zeroes tx/ty and there is no friction or deceleration. Correct for Zelda, wrong for Mario; the chapter shows the workaround rather than pretending.

examples/jrpg/ — four-direction walking with per-facing animation, a Tiled town map, NPCs spawned from map objects, a text box, and a party member as a child actor. Exercises null-gravity arcade physics, the full four-way state mask, characters with per-facing sprite mappings, actors auto-created from object layers, akgl_text_*, parent/child actors (children are snapped to the parent and never simulated — a documented behaviour this game depends on).

The two are deliberately complementary: the sidescroller is the physics tutorial, the JRPG is the content-pipeline tutorial.

---

Part 4 — Assets

docs/tutorials/assets/ holds a curated CC0 subset from Kenney.nl, with:

• LICENSE — the CC0 deed text.
• PROVENANCE.md — an aligned table, one row per file: which pack, the source URL, and what it was cropped or repacked into.
• scripts/fetch_tutorial_assets.sh — refreshes from upstream into a temp directory and moves into place only after verifying the fetch and sanity-checking the contents. This is exactly the shape mkcontrollermappings.sh was fixed into for 0.5.0: check curl's status, check a plausible minimum, never overwrite a good tracked copy from a failed run, exit non-zero. Do not reintroduce the version that silently destroyed its own fallback.

CC0 specifically, not merely "free": a reader who copies a tutorial into their own game inherits whatever obligation the assets carry, and CC0 carries none.

Asset contract, fixed up front so the art and the game code can be built in parallel: 16×16 tiles, 32×32 character frames, sheets counted left-to-right from the top-left as akgl_spritesheet_initialize expects, at most AKGL_SPRITE_MAX_FRAMES (16) frames per animation with frame ids that fit a uint8_t. Maps are Tiled TMJ with embedded tilesets, under AKGL_TILEMAP_MAX_LAYERS (16) and AKGL_TILEMAP_MAX_OBJECTS_PER_LAYER (128). Actor objects use "type":"actor" with a character string property and a state int property; the string-array form works in character JSON and is not accepted here.

Corrected during execution. This contract originally said external tileset references, quoting README.md: "The engine ONLY supports TilED TMJ tilemaps with tileset external references." That is backwards, and it is one more stale claim of the kind this project exists to fix. "source" appears nowhere in src/tilemap.c; nothing in the library ever opens a .tsj. akgl_tilemap_load_tilesets_each (src/tilemap.c:139-159) reads columns, firstgid, tilecount and image directly off each element of the map's tilesets array, and tests/assets/testmap.tmj is embedded. An external stub fails with AKERR_KEY on the missing columns.

Four further constraints verified against the loader, all of which bind the tutorial maps:

• Every object in an object group needs a type string, plain rectangles included. A missing type fails the whole load.
• Perspective markers need "type": "perspective", not merely the name p_foreground/p_vanishing. The loader checks the type first and silently ignores the object otherwise.
• A literal 512×512 map is rejected. Both bounds use >=, so 262,144 cells is one too many; 512×511 is the largest that loads.
• Tileset images resolve through akgl_path_relative (canonicalized, absolute paths work) but image-layer images resolve through a plain "%s/%s" join (absolute paths do not). Keep every image path relative to the map file.

A defect found while planning

tests/assets/World_A1.png and util/assets/Actor1.png carry the default filenames of RPG Maker's bundled art and have no license file, while tests/assets/akgl_test_mono.ttf sits beside akgl_test_mono.LICENSE.txt. RPG Maker's bundled assets are licensed to users of that product; redistributing them inside a C library is not something that license covers.

This plan does not fix it — replacing test fixtures is a separate change with its own blast radius, and it is not blocking the docs. It does two things: the tutorial assets get a clean provenance story that does not depend on those files, and the finding goes into TODO.md with file, functional consequence and blast radius, per the house practice of documenting defects against yourself.

---

Part 5 — How the work is split across subagents

Wave 1 runs entirely in parallel. Nothing waits on docs/ existing, because the asset contract, the block grammar and the status tables are all pinned above — that is what lets the tutorial work start immediately rather than queueing behind the manual.

Agent	Deliverable	Depends on
A — harness	tests/docs_examples.sh, preludes, setups, tools/docs_checkjson.c, the screenshot pair, CMake wiring, the harness spec section in README.md	nothing
B — assets	Kenney CC0 subset, LICENSE, PROVENANCE.md, fetch script, both Tiled maps, sprite/character JSON	the asset contract
C — sidescroller	examples/sidescroller/ + chapter 19	asset contract (B's bytes arrive later)
D — JRPG	examples/jrpg/ + chapter 20	asset contract
E — core	04 errors (owns the three tables), 05 heap, 06 registry, 07 game/frame, 21 appendix	nothing
F — presentation	08 rendering + embedding, 09 drawing, 10 sprites, 11 characters, 12 actors	nothing
G — world	13 tilemaps, 14 physics, 15 input	nothing
H — periphery + front matter	16 text, 17 audio, 18 utilities, 01 intro, 02 philosophy, 03 getting started	nothing

Agent E's status tables are the one wave-1 artifact other agents consume, so E publishes them first, before writing prose. Every other chapter cites them rather than re-listing codes locally.

Every chapter agent gets the same five standing instructions, because the failure this project exists to fix is documentation asserting things nobody checked:

1. Read src/, not the header prose. The physics.engine and akgl_registry_init claims are both false and have been quoted forward. "A premise nobody has re-checked is where the next defect is hiding."
2. Reference upstream, do not restate it. If the sentence you are writing would still be true in a project that does not use libakgl, it belongs in a link. Cite the specific upstream document; do not paraphrase it.
3. Every fence carries an info string. Prefer run=, then wrap=, then excerpt=; a norun block is a decision that has to be justified.
4. Do not restate signatures — link the Doxygen reference, or excerpt= the header.
5. Note the known defect where a reader would hit it, with the guard to apply, linked to TODO.md.

Wave 2 is the integration pass, and the only genuinely serial step: build the TOC, insert cross-references between chapters and both tutorials, verify no chapter re-teaches upstream material, reconcile terminology, cut the README's FAQ half, add the TODO.md entries, then run the full gate.

Verification

cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build --parallel
ctest --test-dir build --output-on-failure

Iterating on one chapter without a full run:

./tests/docs_examples.sh --root . --cflags-file build/docs_cflags.txt docs/14-physics.md

Specific things that must hold before this is done:

• ctest -R docs_examples passes, and its census line accounts for every block. A rising norun count is the harness being talked out of its job, and is a review finding.
• ctest -R docs_screenshots passes with no figure regenerated.
• Every status code in include/akgl/error.h appears in Table 1, and every status the library actually raises appears in Table 2 — checked by grepping src/ for FAIL_* and AKERR_ status arguments, not by reading the headers.
• Both example games build, and their headless smoke runs exit 0.
• ctest -R api_surface and -R headers still pass — writing a subsystem chapter tends to turn up a symbol declared nowhere, which is precisely what api_surface is for.
• doxygen Doxyfile is still clean; WARN_AS_ERROR = FAIL_ON_WARNINGS means a header touched while documenting must stay fully documented.
• scripts/reindent.sh --check is clean — examples/ and tools/ are C sources in this tree and the pre-commit hook will reindent them.
• scripts/memcheck.sh -R docs_examples — the run= blocks execute real library code and are a genuine new memory-check vehicle, which is the shape AGENTS.md asks for ("a new path worth checking belongs in a benchmark, where it gets both").
• Every commit names the agent program, model and version as co-author, per AGENTS.md.

Out of scope, deliberately

• Replacing the RPG-Maker-named test fixtures (recorded in TODO.md instead).
• Fixing the false claims in physics.h and registry.h. The chapters document what the code does; correcting the header comments is a separate commit, since AGENTS.md requires style and behaviour changes to stay unbundled.
• Implementing arcade_collide, terminal velocity, or friction. The tutorials work around them and say so.
• Documenting libakerror, libakstdlib, SDL3, jansson or the Tiled format. Linked, not restated — see the governing editorial rule.