- README: how the pieces fit, adding Crafter.Debug to a project
(Debug::Use, the shared-args rule, Session and Pump, the AGENTS.md
checklist), the app-side API with examples, the fixed-step and
Crafter.Graphics patterns, a shim module for calls without #ifdefs,
and the agent side: commands, exit codes, stopping apps, attaching
a debugger, version skew.
- AGENTS.template.md: the configurations and partitions, commands,
test conventions (including the dangling Value::Find pointer two
tests hit), style, design rules, security and gotchas.
- tooling/AGENTS.consumer.md: what every consumer's agents read in
each session, kept short: the loop, exit codes and the gotchas,
pointing at `crafter-debug guide` for the rest.
The QUIC transport the README describes lands next.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A consumer loads Crafter.Debug.Build through
#pragma crafter dependency "<Crafter.Debug>" project "tooling/project.cpp"
and calls Debug::Use in its own CrafterBuildProject, the way
Crafter.LintRules gets in. With the consumer's flag on, Use adds the
library from the checkout the pragma loaded, and writes
build/crafter-debug: a POSIX sh launcher for the client that library
builds. The client is one of the library's dependencies, so a debug
build compiles it in the same pass as the app, from the same sources.
Why a launcher and not a script: every `crafter-build run` loads the
whole project first, which costs 13-28 s per call on 3DForts (a git
pull per unpinned dependency plus rescanning sources), while the
launcher is one sandbox start, 0.08 s. A client built in the Flatpak
links the Flatpak's libc++ against the runtime's glibc, so the launcher
starts it through `flatpak run` and never on the host itself; inside a
CrafterBuild sandbox it runs it directly.
The library, the client and examples/Basic are placeholders that prove
the wiring: the debug build writes a launcher whose client exists, a
plain build has no Crafter::Debug symbols and keeps the notes from
tooling/AGENTS.consumer.md, and a fresh plain build writes a stub that
names the flag.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
