AGENTS.md

Guidance for agents working in this repo.

Structure

Parent repo integrates five submodules built and packaged for Debian 13: libg15, libg15render, g15daemon, g15macro, g15stats.
packaging/ holds all build/CI logic; .gitea/workflows/ and .github/workflows/ both call into the same shared scripts rather than duplicating build logic.

bash packaging/local-build.sh (also available as the default VS Code build task) builds all five Debian source+binary packages into gitignored dist/, and extracts plain executables/shared libraries into gitignored bin/.
packaging/build.sh requires every submodule to be clean (git status --porcelain --untracked-files=all empty) and checked out exactly at its parent's pinned gitlink commit — it refuses to build otherwise. Regenerable host build artifacts (autotools Makefile, config.*, libtool, stamp-h1, .deps/) left over from a manual ./configure && make are untracked but still count as dirty; remove them (safe, regenerable) rather than committing them.
packaging/run.sh / packaging/ci.sh wrap build.sh+test.sh in disposable Docker containers for host/CI use; inside this devcontainer (already root, already /.dockerenv, already has all packaging tools installed) build.sh/test.sh can be run directly without nested Docker.
See packaging/NOTES.md for full packaging/versioning/CI policy details.

Commit and push submodule changes in the submodule's own repo first, then update and push the parent gitlink pointer — this keeps the parent's gitlink always fetchable.
Never blindly git add -A a submodule; stage real source/doc changes explicitly and exclude generated build state.

g15stats renders on a bitmap-only canvas allocation; do not switch it to the ABI-dependent (optionally TTF-enabled) libg15render canvas initializer — a smaller bitmap-only allocation plus a larger installed renderer ABI has previously corrupted the heap at startup (malloc(): invalid size).