docs: keep this repository's agent notes in AGENTS.template.md

This repository now uses the template itself. AGENTS.md is written by
the self-host build and `test` and is gitignored, so the notes
Crafter.Math ships reach the agents working here, and a change to them
no longer leaves a tracked file modified, which also made every build
afterwards a dirty-tree version, a new crafter.build-lib variant and a
full rebuild.

The gotcha that described the old arrangement now says where to edit,
that a fresh clone or worktree has no AGENTS.md until its first build
(./build.sh does not write it), and what an older harness does to the
generated file. The paths table and the never-commit list name both
files. The CI error for a missing signing key and a manifest comment
point at the template, since the forge no longer shows an AGENTS.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.forgejo/workflows/ci.yaml

@@ -140,7 +140,7 @@ jobs:
           # (/etc/crafter-flatpak: signing-key.asc and key-id) and mounted
           # read-only; it is imported into a throwaway keyring per run.
           if [ ! -s /run/crafter-flatpak/signing-key.asc ] || [ ! -s /run/crafter-flatpak/key-id ]; then
-            echo "no signing key under /etc/crafter-flatpak on the runner host; generate it as described in AGENTS.md (CI and publishing)" >&2
+            echo "no signing key under /etc/crafter-flatpak on the runner host; generate it as described in AGENTS.template.md (CI and publishing)" >&2
             exit 1
           fi
           export GNUPGHOME=$(mktemp -d)

.gitignore

@@ -5,3 +5,5 @@ share/crafter-build/
 .claude
 # written by CI next to the manifest so relative source paths still resolve
 packaging/flatpak/ci-manifest.yaml
+# written by every build and test run from AGENTS.template.md
+/AGENTS.md

AGENTS.template.md

@@ -11,6 +11,7 @@ crafter-build is a C++26 modules build system. A project is described by a `proj
 | `interfaces/Crafter.Build-<Partition>.cppm` | Module interface partitions. `Crafter.Build.cppm` is the umbrella that re-exports them. |
 | `implementations/Crafter.Build-<Partition>.cpp` | Implementation units, one per partition, named `Crafter.Build:<Partition>_impl`. `main.cpp` is a thin wrapper around `Crafter::Run`. |
 | `project.cpp` | The self-host build description: a `crafter.build-lib` library, a `crafter.build-exe` executable, the test declarations, the lint rules and the `flatpak` and `install` scripts. |
+| `AGENTS.template.md` | The source of AGENTS.md. Every build and test run writes AGENTS.md from it, with the notes the dependencies ship; AGENTS.md is gitignored, so changes go here. |
 | `tests/<Name>/main.cpp` | One self-test per directory; `tests/<Name>/fixture/` holds the sample project it builds. |
 | `examples/` | Standalone user-facing projects, MIT licensed. |
 | `build.sh` | Bootstrap script. It compiles everything by hand, without crafter-build. |
@@ -141,7 +142,7 @@ These were decided deliberately. Do not undo them without the maintainer's say-s
 - Separate commits for the fix, its test and the README change when each stands on its own.
 - Update the README in the same PR when user-visible behaviour changes.
 - `format`, `lint` and `test` green before pushing. CI builds the Flatpak and runs the suite inside it on PRs, publishes the `beta` branch of the Catcrafts repo on every push to `master`, and the `stable` branch plus a release on an `X.Y.Z` tag.
-- Never commit `bin/`, `build/`, `share/crafter-build/`, `lib/*.a` or fixture build outputs (all gitignored), and never edit the vendored files in `lib/`.
+- Never commit `bin/`, `build/`, `share/crafter-build/`, `lib/*.a`, `AGENTS.md` or fixture build outputs (all gitignored), and never edit the vendored files in `lib/`.
 - Keep `CRAFTER_BUILD_MARCH=x86-64-v2` in the manifest for the shipped binary: it has to run on any x86_64 machine. User projects still default to `native`.
 
 ## Security considerations
@@ -194,4 +195,4 @@ Local builds are two scripts in `project.cpp`. Run them with the native binary:
 - The wasm compile flags live in one place, `WasmBaselineFlags` in `Crafter.Build-Clang.cppm`: the std module and every unit have to agree on them, and `VariantId()` and the std PCM directory hash them, so a change rebuilds instead of mixing old and new BMIs. They enable C++ exceptions, so the link takes the exception-enabled libc++ and libunwind from the sysroot's `lib/<triple>/eh/` (wasi-sdk 33 and later). The Flatpak's sysroot has them and a distro's may not; where they are missing the wasm tests skip, so run those through the Flatpak. A browser page checks the engine with the `WasmBaselineProbes` named in `variants.json`.
 - `WasiBrowserRuntimeExit` runs `wasi-runtime/runtime.js` under node and skips where there is none. The Flatpak has no node, so CI never runs it: after touching `runtime.js`, run the suite in the native loop with node on `PATH`.
 - `VariantId()` names the output directory, so CI globs `bin/crafter.build-exe-<target>-<march>-*/` rather than predicting the hash. The hash includes the compiler, so after a toolchain update the previous variant's directories stay in `bin/` and `build/` until `clean`, and such a glob matches both.
-- This repository has no `AGENTS.template.md`, so the self-host build and `test` leave this file alone, and the `AGENTS.consumer.md` Crafter.Math ships does not reach it. A template would make this file build output: it would go into `.gitignore`, and a fresh clone or worktree would have no AGENTS.md until its first build.
+- AGENTS.md is build output: the self-host build and `test` write it from `AGENTS.template.md`, with the `AGENTS.consumer.md` of each dependency that ships one (Crafter.Math, today) merged in, and it is gitignored. Edit the template; an edit made in AGENTS.md is gone after the next build. A fresh clone or worktree has no AGENTS.md until its first `./bin/crafter-build` or `test`, since `./build.sh` does not write it. A harness from before the template (3.0.0 and older) never creates one and keeps its section in one it finds; the next build with a current harness writes it over.

packaging/flatpak/net.catcrafts.CrafterBuild.yaml

@@ -224,7 +224,7 @@ modules:
     build-options:
       # The self-host build fetches Crafter.Math, Crafter.Asset,
       # Crafter.LintRules and glslang from git; they are unpinned on purpose
-      # (sibling repos tracking their default branch, see AGENTS.md).
+      # (sibling repos tracking their default branch, see AGENTS.template.md).
       build-args:
         - --share=network
       # On this module, not at the top of the manifest: top-level build