feat(agents): keep dependencies' AGENTS.consumer.md in AGENTS.md

An agent working on a crafter-build project reads its AGENTS.md, and
learns nothing there about the libraries the project builds against
unless someone copied that in by hand. This repository shows the cost:
the code style section of its AGENTS.md restates what Crafter.LintRules
enforces, and goes stale whenever the rules change.

A library now ships those notes itself, as AGENTS.consumer.md beside
its project.cpp; nothing in its project.cpp changes. When a consumer
has an AGENTS.md beside its own project.cpp, `crafter-build` and
`crafter-build test` keep a section in it, between two marker comments,
holding its dependencies' notes. The section is appended the first time
and rewritten in place after that. The file is written only when the
section changes, and an AGENTS.md is never created. lint, format, run
and clean leave it alone. The update runs after loading, which has just
fetched every dependency, and before compiling, so a build that fails
still has the notes.

cfg.dependencyNotes picks the dependencies. Transitive, the default,
follows `dependencies` all the way down from the project's own
configurations, its tests and its `#pragma crafter dependency` tooling;
Direct stops at the first loaded project on each path; None removes
the section. A dependency's own pragma tooling never counts: it is
about how that dependency is built, not how it is used, and being no
`dependencies` edge it is never reached. Nor are a dependency's tests:
nothing builds them for the consumer, and their configurations can
point at a local their project file has since moved out of.

The walk has to know which Configurations belong to another project,
and where that project lives, and cfg.path cannot say: only the
Configuration GitProject and LocalProject return is rebased, so a
dependency's internal configurations keep "./", which resolves to the
consumer. The loader records it instead, LoadedProjectOf beside the
project cache, and keeps what the root's pragmas resolved to past the
frame LoadProject pops, PragmaDependencies. Neither is exported.

The markers count only as whole lines outside fenced code blocks, so
documentation can quote them. Unbalanced markers and a document ending
inside a code block leave the file alone with a warning: guessing which
part of someone's file is generated would overwrite their text, and
missing the section would add another one on every build. A note that
would break the section when it is read back, through a marker line of
its own or a code block it never closes, is left out with a warning.
The file is replaced through a temporary renamed onto the symlink's
target, so a linked AGENTS.md stays a link and a write cut short leaves
the old file rather than part of the new one.

The code is a new partition, Crafter.Build:Agents, listed in build.sh,
CrafterBuildModules, project.cpp and the umbrella.

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

interfaces/Crafter.Build-Agents.cppm

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+// SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®
+
+export module Crafter.Build:Agents;
+import std;
+namespace fs = std::filesystem;
+
+// Dependency notes. A crafter-build project ships an AGENTS.consumer.md beside
+// its project.cpp, written for the agents of the projects that depend on it,
+// and crafter-build keeps those files in each consumer's AGENTS.md. Without
+// that, an agent working on a consumer knows nothing about the libraries it
+// builds against unless someone copied the knowledge in by hand, and a copy
+// goes stale the moment the library changes.
+export namespace Crafter {
+    struct Configuration;
+
+    // Which dependencies' notes a project's AGENTS.md carries: the value of
+    // Configuration::dependencyNotes.
+    enum class DependencyNotes {
+        // The projects this one builds against, and the projects those build
+        // against, all the way down.
+        Transitive,
+        // Only the projects this one's own configurations, tests and
+        // `#pragma crafter dependency` lines name.
+        Direct,
+        // None. A section an earlier build wrote is removed.
+        None,
+    };
+
+    // One dependency's AGENTS.consumer.md, ready to merge.
+    struct DependencyNote {
+        // Where it came from, written into the comment above it: the git URL,
+        // or for a local project the file's path relative to the consumer.
+        std::string source;
+        // The file's content, without leading blank lines or trailing
+        // whitespace.
+        std::string text;
+    };
+
+    // `agentsMd` with its dependency notes section holding `notes`, in order.
+    // A file without a section gets one appended after a blank line; one
+    // with a section has it rewritten in place, wherever it was moved to;
+    // and empty `notes` remove it together with that blank line, so a file
+    // that only ever gained the section gets its own bytes back.
+    //
+    // The two marker lines count only as whole lines outside fenced code
+    // blocks, which is what lets a document quote them. Throws, naming the
+    // line, when the markers are unbalanced or the document ends inside a
+    // code block: guessing which part of someone's file is generated would
+    // overwrite their text, and missing the section would add a second one
+    // on every build. Also throws for a note that would break the section
+    // when it is read back: one with a marker line of its own, or a code
+    // block it never closes.
+    std::string MergeDependencyNotes(std::string_view agentsMd, std::span<const DependencyNote> notes);
+
+    // Refresh the dependency notes section of the AGENTS.md beside
+    // `projectFile` from the AGENTS.consumer.md of every dependency
+    // project.dependencyNotes selects. `project` is the Configuration that
+    // file returned, after LoadProject: loading is what found the
+    // dependencies. Does nothing when there is no AGENTS.md, which is never
+    // created. Writes only when the text changes, and returns whether it
+    // did. An unreadable file, a failed write, malformed markers and a
+    // dependency's unusable notes are warnings: the notes never fail a build.
+    bool UpdateAgentsMd(const Configuration& project, const fs::path& projectFile);
+}