Add `AGENTS.md` guidance for AI coding agents, at the root and in the folders they change most

[rickroesler]

Follows the pretext-dev thread "Claude skill for pretext authoring" (https://groups.google.com/g/pretext-dev/c/0D90duVchZg), where a root AGENTS.md was proposed and I offered to write it. This issue records what the files would contain and how they would be organized, so the shape is agreed before the pull request.

AGENTS.md is the file format that AI coding agents (Codex, Cursor, GitHub Copilot and others, per https://agents.md) read for repository-specific instructions. Claude Code reads CLAUDE.md instead, so the pull request also adds a root CLAUDE.md whose whole content is a pointer to AGENTS.md. An agent reads the root file plus the file in whichever directory it is editing, so the folder files can be short and specific.

Audience. These files are for anyone, human or agent, changing the PreTeXt toolchain itself: stylesheets, schema, the Python script, CSS and JavaScript, the Guide, the sample documents. Guidance for authors writing a book in PreTeXt is a different deliverable (a skill leaning on the schema, the sample documents and validation, as suggested in the thread) and is out of scope here.

Principle: link, do not duplicate. The repository already has 45 README.md files, and they answer "what is this folder" well. What no file answers today is "what else must change when I change this, and how do I check it." Each AGENTS.md carries only that second kind of fact and links to the README for the first. Everything in them is traceable to an existing README, a chapter of the Guide, or the git history; nothing is invented for the occasion.

Proposed files. Eight AGENTS.md, each under about 80 lines, the root under 120.

File	Carries what is written down nowhere else
AGENTS.md	Tool prerequisites; the multi-surface change pattern; commit and branch contract; which files are generated and never hand-edited; how to verify a change; pointers to CONTRIBUTING.md, the Guide's developer chapters, legal/copyright-holders.md
xsl/AGENTS.md	XSLT 1.0 with EXSLT only, xsltproc as reference processor; the linear import chain and the -common naming rule; PTX:BUG: versus PTX:WARNING: messages; copyright header on new files; a change to publisher-variables.xsl pairs with schema/publication-schema.xml
schema/AGENTS.md	Only pretext.xml and publication-schema.xml are edited; .rnc and .rng are regenerated with xsltproc and trang; build.sh hard-codes a path; pretext-dev must stay purely additive
pretext/AGENTS.md	Python 3.10 minimum; no automated test suite; one-way import graph out of common.py; how a new generated-asset type threads through xsl/extract-*.xsl, lib/pretext.py, component_dirs and the -c vocabulary; copy pretext.cfg to user/, never edit it
css/AGENTS.md	css/dist is committed and rebuilt, never hand-edited, in the same pull request as the source change; a new theme or theme option also needs the option table in xsl/publisher-variables.xsl; examples/custom-theming is the smoke test; components are shared, targets are owned
js/AGENTS.md	js/dist is committed and rebuilt likewise; prism/, diagcess/ and jQuery are vendored; bundle order in pretext-core.js is deliberate; the CLI consumes dist as-is
examples/AGENTS.md	sample-article gains an example for every new feature; minimal stays small and is for isolating bugs; which examples carry their own toolchain (webwork, pug, sample-book/gdpractice)
doc/guide/AGENTS.md	Where a new element or publisher option is documented (Overview plus Topics; the Publication File reference plus the relevant Publisher chapter), from developer/coding.xml; elaborate examples belong in the Showcase Article, not the Guide; generated/ is build output

Not proposed: script/, journals/, fonts/, legal/. Their READMEs already state the rules; the root file points at them.

The worked example. PR #3148 (SVG favicon) is the template the root file uses for "one feature, several surfaces":

HTML: add SVG option for favicon-scheme
Publisher variables: add svg favicon option
Schema: add publisher option for SVG favicon
Sample article: change favicon to SVG
Guide: document SVG favicon option

The same pattern recurs across the last two years of history (Beamer options, GeoGebra play button, DoenetML, FITB), so it is stated as the norm, alongside the commit-subject convention it illustrates: Area: lowercase description, no period, one line, XML names in double quotes.

Verification. There is no CI in this repository, so the root file says what checking a change means here, using commands taken from the READMEs and Guide where they exist and otherwise composed from the same documented tools:

• expand XInclude with xmllint and validate with jing, the minimal example against schema/pretext.rng and the sample article against schema/pretext-dev.rng
• build examples/minimal or examples/sample-article with xsltproc
• run xsl/tests
• regenerate the schema; rebuild css/dist and js/dist when their sources moved.

Each command is run once before it goes in the file. The installed CLI bundles a frozen copy of the core, so pretext build and pretext validate do not test a checkout; the root file says so.

Personal layers. Andrew's concern in the thread, that a committed file leaves no room for personal instructions, is handled by the tools rather than by this repository: Codex reads ~/.codex/AGENTS.md, Claude Code reads ~/.claude/CLAUDE.md, and Claude Code also reads a per-checkout CLAUDE.local.md. The pull request adds CLAUDE.local.md to .gitignore and the root CLAUDE.md says so in one line. The committed files stay canonical and tool-neutral.

Out of scope. An author-facing skill; any CI configuration; a release-notes file (removed deliberately in favor of the history).

Suggested shape: one pull request, one commit per file so each surface reviews on its own, no other changes riding along.

Claude Fable 5.1, acting as a coding assistant for Rick Roesler