From c2e8bf0a93e6833b783a1f65aab41be059ca73eb Mon Sep 17 00:00:00 2001 From: Jorijn van der Graaf Date: Sat, 31 Oct 2026 03:18:26 +0100 Subject: [PATCH] docs: dependency notes in the README What a library ships and where, what a consumer's AGENTS.md gets and when it is written, the section's format, and what cfg.dependencyNotes selects. Co-Authored-By: Claude Opus 5.5 --- README.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/README.md b/README.md index b7e0d46..bb4b533 100644 --- a/README.md +++ b/README.md @@ -94,6 +94,38 @@ import Crafter.LintRules; #pragma crafter dependency "" [branch "" | commit ""] [project ""] ``` +### Dependency notes for agents + +An agent working on a project reads its `AGENTS.md`, which says nothing about the libraries the project builds against unless someone copied that in by hand. A library ships it instead: an `AGENTS.consumer.md` beside its `project.cpp`, written for whoever uses the library rather than whoever works on it. When a consumer has an `AGENTS.md` beside its own `project.cpp`, `crafter-build` and `crafter-build test` keep its dependencies' notes in a section of it: + +```markdown + + + + +## Crafter.Math + +... + + +``` + +- Each file goes in as written, under a line naming where it came from: the git URL, or for a `LocalProject` the file's path relative to the consumer. It lands among the consumer's own headings, so start it with a `##` heading that names the library. +- The section is appended the first time and rewritten in place after that, wherever it has been moved to. Edits inside it are lost on the next build; the rest of the file is never touched. The file is written only when the section changes, and an `AGENTS.md` is never created. +- The update runs after `project.cpp` loads and before anything compiles, so a build that fails still has the notes. `lint`, `format`, `run` and `clean` leave the file alone. +- An unpinned dependency's notes follow its default branch, as its code does, so the section can change on any build. Pin a `commit` to decide when. +- Unbalanced markers leave the file as it is, and a notes file that would break the section (a code block it never closes, a marker line of its own) is left out; both are reported as warnings. Markers quoted inside a fenced code block don't count. + +`cfg.dependencyNotes` picks the dependencies: + +| Value | Notes from | +|---|---| +| `DependencyNotes::Transitive` (default) | everything the project builds against, all the way down: its `dependencies`, its tests' dependencies and its own `#pragma crafter dependency` tooling | +| `DependencyNotes::Direct` | only the projects the project's own configurations, tests and `#pragma crafter dependency` lines name | +| `DependencyNotes::None` | none, and a section from an earlier build is removed | + +Two things never count: the project's own `AGENTS.consumer.md`, and a dependency's `#pragma crafter dependency` tooling, which is about how the dependency is built, not how it is used. + ## Tests Tests live under `tests//`. The simplest case is a single C++ file: