Add AGENTS.md guidance for coding agents (#3210)

.gitignore

@@ -24,3 +24,6 @@ css/dist/*.map
 
 # jsbuilder output
 js/dist/**/*.map
+
+# per-checkout agent instructions
+CLAUDE.local.md

AGENTS.md

@@ -0,0 +1,84 @@
+<!--********************************************************************
+Copyright (C) 2026  Robert A. Beezer
+
+This file is part of PreTeXt.
+
+PreTeXt is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 2 or version 3 of the
+License (at your option).
+
+PreTeXt is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
+*****************************************************************-->
+# Working on PreTeXt
+
+PreTeXt is an authoring and publishing system for textbooks, research articles, and monographs. These instructions serve people and agents changing the toolchain, not authors writing books; start with the [project overview](README.md).
+
+## Prerequisites
+
+- Install `xsltproc` as described in the [developer processing chapter](doc/guide/developer/xsltproc.xml), and `trang` plus `jing` as described in the [schema notes](schema/README.md) and [schema chapter](doc/guide/author/schema.xml).
+- The [Python package](pretext/README.md) requires Python 3.10 or newer and its `requirements.txt` dependencies.
+- Use Node.js 18 or newer with the Node package manager (npm) for both asset builders; the locked `esbuild` dependency of each requires Node.js 18 even though the CSS builder's `package.json` states 14.
+- Build examples with the `pretext` command-line interface (CLI) from the separate `pretext-cli` project.
+
+## Change contract
+
+- A new publication option normally changes `schema/publication-schema.xml` and its generated schemas, `xsl/publisher-variables.xsl` or another implementing stylesheet, an example, and the Guide. Keep each surface in its own commit.
+- Pull request (PR) #3148, for an SVG favicon, demonstrates the pattern with these commits:
+
+      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
+
+- [Careful documentation accompanies every new feature](doc/guide/developer/coding.xml).
+- Commit subjects use `Area: lowercase description`, omit a trailing period, stay on one line, and stay within roughly 60 to 70 characters, per the [Git chapter](doc/guide/developer/git.xml). Put XML names in double quotes, such as `"@font-size"`. Bodies are rare.
+- Current areas include Schema, Publication schema, Publisher variables, HTML, LaTeX, CSS, JavaScript, Guide, Sample article, Sample book, Assembly, Common, Validation, and Deprecate.
+- Keep one logical change per commit and do not squash your own; maintainers may combine or redistribute commits when merging, as [CONTRIBUTING.md](CONTRIBUTING.md) says.
+- Follow [CONTRIBUTING.md](CONTRIBUTING.md) and the [Git chapter](doc/guide/developer/git.xml): keep one topic per branch, rebase onto the default `master` branch, never merge `master` into a topic, and stop pushing while a PR is under review unless asked.
+- Isolate formatting-only changes and add their commit hashes to `.git-blame-ignore-revs`.
+- New files use the standard copyright header. Record any different holder or notice treatment in [the copyright registry](legal/copyright-holders.md).
+
+## Generated files
+
+- Edit `schema/pretext.xml` and `schema/publication-schema.xml`, not the generated RELAX NG (Regular Language for XML Next Generation) compact `.rnc` or `.rng` files.
+- Edit CSS and JavaScript sources, not `css/dist/` or `js/dist/`; rebuild and commit their generated diffs with the source change.
+- Treat `doc/guide/generated/` as build output.
+- Copy `pretext/pretext.cfg` to `user/pretext.cfg` for local executable settings; never edit the distributed file.
+- Rules for `script/`, `journals/`, and `fonts/` live in their own READMEs: [script](script/README.md), [journals](journals/README.md), [fonts](fonts/README.md).
+
+## Verification
+
+- Expand XML Inclusions (XInclude) directives with `xmllint --xinclude`, then validate the minimal example with `jing`. `xmllint` only expands the includes here; `jing` performs the validation, as the [schema chapter](doc/guide/author/schema.xml) recommends.
+
+      xmllint --xinclude examples/minimal/source/main.ptx > /tmp/minimal.xml && jing schema/pretext.rng /tmp/minimal.xml
+
+- Validate the sample article against the development schema:
+
+      xmllint --xinclude examples/sample-article/sample-article.xml > /tmp/sa.xml && jing schema/pretext-dev.rng /tmp/sa.xml
+
+- Run the Extensible Stylesheet Language Transformations (XSLT) unit test:
+
+      (cd xsl/tests && xsltproc pretext-text-utilities-test.xsl null.xml)
+
+- The installed CLI bundles a frozen copy of this repository's core, so `pretext build` and `pretext validate <target>` exercise the released core. [Link a source install of the CLI to this checkout](https://github.com/PreTeXtBook/pretext-cli/blob/main/docs/core_development.md).
+
+- Build the minimal example with the raw processor, with `$REPO` as the checkout root:
+
+      mkdir -p /tmp/minimal-html && cd /tmp/minimal-html && xsltproc --xinclude --stringparam publisher $REPO/examples/minimal/publication/publication.ptx $REPO/xsl/pretext-html.xsl $REPO/examples/minimal/source/main.ptx
+
+- Regenerate the schema products and compare them with the committed files as described in [schema/AGENTS.md](schema/AGENTS.md).
+- Rebuild generated web assets after their sources change:
+
+      (cd script/cssbuilder && npm install && npm run build)
+      (cd script/jsbuilder && npm install && npm run build)
+
+- There is no continuous integration (CI) here; run the checks above locally before opening a PR.
+- Do not add CI configuration, and do not recreate `release-notes.md`; the git history is the release record. `script/mbx` is a retired stub; use `pretext/pretext`.

CLAUDE.md

@@ -0,0 +1,20 @@
+@AGENTS.md
+<!-- Personal, per-checkout additions go in CLAUDE.local.md, which is gitignored. -->
+<!--********************************************************************
+Copyright (C) 2026  Robert A. Beezer
+
+This file is part of PreTeXt.
+
+PreTeXt is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 2 or version 3 of the
+License (at your option).
+
+PreTeXt is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
+*****************************************************************-->

css/AGENTS.md

@@ -0,0 +1,27 @@
+<!--********************************************************************
+Copyright (C) 2026  Robert A. Beezer
+
+This file is part of PreTeXt.
+
+PreTeXt is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 2 or version 3 of the
+License (at your option).
+
+PreTeXt is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
+*****************************************************************-->
+
+# CSS
+
+- Read the [CSS architecture](README.md) and [component layout](components/README.md). Files under a target folder are owned by that target (see the README's ownership section); components are shared and require testing across every target that uses them; colors supply reusable palettes.
+- Legacy themes are hand-maintained CSS in `legacy/`. Modern themes use Sassy CSS (SCSS) in `targets/html/<name>/`; follow the [city naming convention](targets/html/README.md).
+- `dist/` is committed build output. Never edit it by hand; rebuild it from `../script/cssbuilder/` and include its diff with the source change.
+- Theme names and their accepted options are enumerated in the `html-theme-option-list` table in `../xsl/publisher-variables.xsl`; `$html-theme-name` reads the publication file's `html/css/@theme`. A new theme or option updates that table and the Guide. Check whether `../schema/publication-schema.xml` describes the option before relying on validation: the committed publication schema does not yet accept every option that the publication files in `../examples/custom-theming/publication/` use.
+- Use Node.js 18 or newer with the Node package manager (npm): the builder's `package.json` states 14, but its locked `esbuild` dependency requires 18. Rebuild with `(cd ../script/cssbuilder && npm install && npm run build)`.
+- Smoke-test themes in [`examples/custom-theming`](../examples/custom-theming/README.md). Its PreTeXt command-line interface (CLI) target can rebuild only custom theme CSS with `pretext build web-custom-theme -t` (with the CLI linked to your checkout).

doc/guide/AGENTS.md

@@ -0,0 +1,28 @@
+<!--********************************************************************
+Copyright (C) 2026  Robert A. Beezer
+
+This file is part of PreTeXt.
+
+PreTeXt is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 2 or version 3 of the
+License (at your option).
+
+PreTeXt is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
+*****************************************************************-->
+
+# The PreTeXt Guide
+
+- Follow [README.md](README.md) for build commands and for the `tag`, `tage`, and `attr` markup used when writing about syntax.
+- Follow the [developer documentation contract](developer/coding.xml). Mention a new element briefly in Overview, describe it fully in Topics, and cross-link both locations. Put elaborate examples in the Showcase Article, `examples/showcase`, not in the Guide.
+- Give a new publisher option a terse entry in `publisher/publication-file.xml`, ordered lexicographically by its XPath expression. Add the fuller explanation to the relevant Publisher chapter and cross-link the two locations.
+- Apply the [Basics Reference rules](basics/README.md) when editing that part, including its identifier, cross-reference, snippet, and index conventions.
+- Put a setting in `docinfo` when it changes the document's content or meaning. Put it in the publication file when it changes presentation or selects whole authored units; defaults follow the authored attribute they govern.
+- Treat `generated/` as build output.
+- Some Guide files have additional copyright holders. Preserve their notices exactly as recorded in [the copyright registry](../../legal/copyright-holders.md).

examples/AGENTS.md

@@ -0,0 +1,29 @@
+<!--********************************************************************
+Copyright (C) 2026  Robert A. Beezer
+
+This file is part of PreTeXt.
+
+PreTeXt is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 2 or version 3 of the
+License (at your option).
+
+PreTeXt is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
+*****************************************************************-->
+
+# Examples
+
+- Use the [examples index](README.md) to choose the right fixture.
+- `sample-article` is the kitchen sink and gains an example for each new feature. `showcase` demonstrates features, authoring practices, and documentation for authors who learn from examples; elaborate examples belong there (see [its README](showcase/README.md)), while `sample-article` exercises everything. `sample-book` demonstrates book structure. Preserve its content notices exactly as recorded in [the copyright registry](../legal/copyright-holders.md).
+- `minimal` isolates bugs and stays small; [CONTRIBUTING.md](../CONTRIBUTING.md) asks bug reports to add a focused case there. `hello-world` is the bare minimum.
+- [`custom-theming`](custom-theming/README.md) is the CSS smoke test. Treat [`numbering`](numbering/README.md) as a machine-oriented regression fixture.
+- `webwork` uses its `Makefile` plus a local `Makefile.paths`; `pug` uses the Node package manager (npm); `sample-book/gdpractice` contains Godot assets and source. Respect each toolchain when changing those examples.
+- Generated assets belong in an example's configured `generated` or `generated-assets` tree and come from `pretext` script components. Do not edit them by hand; see the [generated-asset example](pdf-fo-development/generated/README.md).
+- Build the relevant target named in its `project.ptx` with `pretext build <target>`, using the PreTeXt command-line interface (CLI), which exercises its bundled core unless linked to this checkout.
+- Validate with `jing`, `pretext.rng` for `minimal` and `pretext-dev.rng` for `sample-article`, using the commands in the [root Verification section](../AGENTS.md).

js/AGENTS.md

@@ -0,0 +1,26 @@
+<!--********************************************************************
+Copyright (C) 2026  Robert A. Beezer
+
+This file is part of PreTeXt.
+
+PreTeXt is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 2 or version 3 of the
+License (at your option).
+
+PreTeXt is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
+*****************************************************************-->
+
+# JavaScript
+
+- `dist/` is committed generated output from the [JavaScript builder](../script/jsbuilder/README.md). Rebuild it with the Node package manager (npm), using `(cd ../script/jsbuilder && npm install && npm run build)`, and commit its diff with the source change. Full builds stay unminified for readable diffs.
+- Treat `diagcess/diagcess.js` (a pre-built npm package) and `jquery.min.js` (loaded from the `js/` root, not `dist/`) as vendored; do not edit them. `prism/gdscript-prism.js` is maintained source that the builder compiles.
+- `src/pretext-core.js` is the core bundle entry. Preserve its deliberate import order when adding an always-loaded script.
+- The separate PreTeXt command-line interface (CLI) copies `js/` and serves the committed files in `dist/` as-is.
+- Use Node.js 18 or newer, as required by `../script/jsbuilder/package.json`.

pretext/AGENTS.md

@@ -0,0 +1,30 @@
+<!--********************************************************************
+Copyright (C) 2026  Robert A. Beezer
+
+This file is part of PreTeXt.
+
+PreTeXt is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 2 or version 3 of the
+License (at your option).
+
+PreTeXt is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
+*****************************************************************-->
+
+# Python package
+
+- Use Python 3.10 or newer and install `requirements.txt`; see [README.md](README.md). `module-test.py` is a manual demonstration rather than an automated test suite.
+- Keep the import graph one-way: `pretext.py`, `webwork.py`, and `stack.py` import `common.py`; `common.py` imports none of those siblings.
+- Transformations run through `lxml` in `common.xsltproc()`, not the `xsltproc` executable.
+- The separate PreTeXt command-line interface (CLI) vendors this layer, so its public function signatures are an interface; preserve them.
+- A new generated-asset type normally adds `../xsl/extract-<name>.xsl` and a function in `lib/pretext.py`. The function builds string parameters, calls `common.xsltproc()`, and invokes external tools through `common.get_executable_cmd()`.
+- Register the asset's destination in `component_dirs` inside `get_destination_directory()` in `pretext`, then add its `-c` or `--component` entry to `component_info` inside `get_cli_arguments()`.
+- Configure external programs in the `[executables]` section. Copy `pretext.cfg` to `../user/pretext.cfg`; never edit the distributed file.
+- Use the `ptxlogger` logger and the `PTX:<LEVEL>: message` console format. At debug verbosity, `release_temporary_directories()` preserves temporary directories for inspection.
+- Run `python3 pretext/pretext -h` from the checkout root with the declared dependencies installed. For a build check use the raw processor command in the root guidance; the installed CLI runs its own bundled copy of this layer.