From 4d39df6232fcf130db377798226b0573315b5f22 Mon Sep 17 00:00:00 2001 From: Rick Roesler Date: Sat, 5 Sep 2026 19:49:38 -0700 Subject: [PATCH 1/9] Agents: add root AGENTS.md guidance for coding agents --- AGENTS.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..c35fef617 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,84 @@ + +# 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 ` 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`. From 0367e1dc0664b01556d7f9e4c1e7a1924ec78186 Mon Sep 17 00:00:00 2001 From: Rick Roesler Date: Sat, 5 Sep 2026 19:49:38 -0700 Subject: [PATCH 2/9] Agents: add stylesheet guidance in xsl/AGENTS.md --- xsl/AGENTS.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 xsl/AGENTS.md diff --git a/xsl/AGENTS.md b/xsl/AGENTS.md new file mode 100644 index 000000000..e1f9c6341 --- /dev/null +++ b/xsl/AGENTS.md @@ -0,0 +1,30 @@ + + +# Stylesheets + +- Use Extensible Stylesheet Language Transformations (XSLT) 1.0 with Extensions to XSLT (EXSLT) only. Declare each EXSLT namespace you use; list a prefix in `extension-element-prefixes` only when you use its extension elements, such as `exsl:document`, not for functions (`pretext-common.xsl` declares `exsl`, `date`, `str`, and `dyn`; `pretext-text-utilities.xsl` also uses `math` and `set` functions). `xsltproc`, backed by libxslt, is the reference processor. +- PreTeXt entry stylesheets load `entities.ent` as an external parameter entity in a `DOCTYPE` (document type declaration). Add shared `-LIKE` and `-FILTER` unions there; its comments identify lists that mirror the schema or require a Guide update. +- Project stylesheets import one format entry point, and every entry point reaches `pretext-common.xsl` through its imports. `pretext-html.xsl` directly imports `publisher-variables.xsl`, `pretext-assembly.xsl`, and `pretext-common.xsl`; publisher variables and assembly are designed to travel together. Treat `-common` stylesheets as libraries rather than entry points. +- Prefix internal logic defects with `PTX:BUG:`. Use `PTX:WARNING:`, `PTX:ERROR:`, and `PTX:FATAL:` according to the [coding chapter](../doc/guide/developer/coding.xml). +- A publisher option change pairs the implementing stylesheet with `../schema/publication-schema.xml`, regenerated schemas, a Guide entry, and an example. A theme option also updates `html-theme-option-list` in `publisher-variables.xsl`. +- Follow the [localization contract](localizations/README.md): add new string identifiers to `en-US.xml`, and register each new language file in `localizations.xml`. Verify localization changes manually. +- Follow the [support-file procedure](support/README.md) when updating Runestone Services versions. +- Copy the copyright header from a sibling onto every new `.xsl` file. +- Run `(cd tests && xsltproc pretext-text-utilities-test.xsl null.xml)`. Add tests there for new low-level text utilities. From d5dc17fb3b3522213abffa4c1ee1642b96bdbfc0 Mon Sep 17 00:00:00 2001 From: Rick Roesler Date: Sat, 5 Sep 2026 19:49:38 -0700 Subject: [PATCH 3/9] Agents: add schema guidance in schema/AGENTS.md --- schema/AGENTS.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 schema/AGENTS.md diff --git a/schema/AGENTS.md b/schema/AGENTS.md new file mode 100644 index 000000000..6edc5947e --- /dev/null +++ b/schema/AGENTS.md @@ -0,0 +1,42 @@ + + +# Schema + +- Edit the literate sources `pretext.xml` and `publication-schema.xml`. The `.rnc` files are generated from them by `xsl/pretext-litprog.xsl` under `xsltproc`, and each `.rng` file by `trang` from its `.rnc`; the full recipe is below. See [README.md](README.md) and `build.sh`. +- `build.sh` contains a hard-coded PreTeXt root variable, `PTX`. Copy it and adapt that path, rather than running the committed script as-is. +- Keep `pretext-dev.rnc`, generated from `pretext.xml`, purely additive over the production schema: a bare include, new named patterns, and choice additions only. +- Put context-dependent checks that RELAX NG cannot express in `pretext-validation-plus.xsl`, whose header and sections describe this role. +- A new element or attribute usually pairs with a stylesheet change, a sample-article example, and documentation in the Guide as [doc/guide/AGENTS.md](../doc/guide/AGENTS.md) describes. +- From the checkout root, regenerate all schema products in a temporary copy and compare every resulting `.rnc` and `.rng` file with the committed version: + + schema_tmp=$(mktemp -d /tmp/pretext-schema-doc.XXXXXX) + cp -a schema/. "$schema_tmp/" + (cd "$schema_tmp" && + xsltproc "$OLDPWD/xsl/pretext-litprog.xsl" pretext.xml && + trang -I rnc -O rng pretext.rnc pretext.rng && + trang -I rnc -O rng pretext-dev.rnc pretext-dev.rng && + trang -I rnc -O rng pf-adapter.rnc pf-adapter.rng && + trang -I rnc -O rng pf-preamble-adapter.rnc pf-preamble-adapter.rng && + xsltproc "$OLDPWD/xsl/pretext-litprog.xsl" publication-schema.xml && + trang -I rnc -O rng publication-schema.rnc publication-schema.rng && + for schema_file in pretext.rnc pretext.rng pretext-dev.rnc pretext-dev.rng pf-adapter.rnc pf-adapter.rng pf-preamble-adapter.rnc pf-preamble-adapter.rng publication-schema.rnc publication-schema.rng; do + diff -q "$OLDPWD/schema/$schema_file" "$schema_file" + done) +- Validate the sample article against `pretext-dev.rng` and the minimal example against `pretext.rng` using the commands in the [root Verification section](../AGENTS.md). From e73b61fc791c6dc714a53a7e860464432db787af Mon Sep 17 00:00:00 2001 From: Rick Roesler Date: Sat, 5 Sep 2026 19:49:38 -0700 Subject: [PATCH 4/9] Agents: add Python package guidance in pretext/AGENTS.md --- pretext/AGENTS.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 pretext/AGENTS.md diff --git a/pretext/AGENTS.md b/pretext/AGENTS.md new file mode 100644 index 000000000..9b0d495ec --- /dev/null +++ b/pretext/AGENTS.md @@ -0,0 +1,30 @@ + + +# 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-.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:: 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. From 8255d10b16749d4812a17bb1f5170c7f2ad573a9 Mon Sep 17 00:00:00 2001 From: Rick Roesler Date: Sat, 5 Sep 2026 19:49:38 -0700 Subject: [PATCH 5/9] Agents: add CSS guidance in css/AGENTS.md --- css/AGENTS.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 css/AGENTS.md diff --git a/css/AGENTS.md b/css/AGENTS.md new file mode 100644 index 000000000..2019eabfe --- /dev/null +++ b/css/AGENTS.md @@ -0,0 +1,27 @@ + + +# 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//`; 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). From d957db9bb29ed2225dec29da32b855c98e1d292f Mon Sep 17 00:00:00 2001 From: Rick Roesler Date: Sat, 5 Sep 2026 19:49:38 -0700 Subject: [PATCH 6/9] Agents: add JavaScript guidance in js/AGENTS.md --- js/AGENTS.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 js/AGENTS.md diff --git a/js/AGENTS.md b/js/AGENTS.md new file mode 100644 index 000000000..b211616c8 --- /dev/null +++ b/js/AGENTS.md @@ -0,0 +1,26 @@ + + +# 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`. From 8547c47db1f47baf90fb82929db05612734d5c83 Mon Sep 17 00:00:00 2001 From: Rick Roesler Date: Sat, 5 Sep 2026 19:49:38 -0700 Subject: [PATCH 7/9] Agents: add examples guidance in examples/AGENTS.md --- examples/AGENTS.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 examples/AGENTS.md diff --git a/examples/AGENTS.md b/examples/AGENTS.md new file mode 100644 index 000000000..9fbf91c50 --- /dev/null +++ b/examples/AGENTS.md @@ -0,0 +1,29 @@ + + +# 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 `, 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). From e567b632ebab1bd0324a6f7e0dbba04c5111d86b Mon Sep 17 00:00:00 2001 From: Rick Roesler Date: Sat, 5 Sep 2026 19:49:38 -0700 Subject: [PATCH 8/9] Agents: add Guide guidance in doc/guide/AGENTS.md --- doc/guide/AGENTS.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 doc/guide/AGENTS.md diff --git a/doc/guide/AGENTS.md b/doc/guide/AGENTS.md new file mode 100644 index 000000000..49802c675 --- /dev/null +++ b/doc/guide/AGENTS.md @@ -0,0 +1,28 @@ + + +# 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). From 4dd6e3983b73a7bc2009d9920c9309bfa4c40c22 Mon Sep 17 00:00:00 2001 From: Rick Roesler Date: Sat, 5 Sep 2026 19:49:38 -0700 Subject: [PATCH 9/9] Agents: point CLAUDE.md at AGENTS.md and ignore CLAUDE.local.md --- .gitignore | 3 +++ CLAUDE.md | 20 ++++++++++++++++++++ 2 files changed, 23 insertions(+) create mode 100644 CLAUDE.md diff --git a/.gitignore b/.gitignore index 56d0f86c1..e5ba9897c 100644 --- a/.gitignore +++ b/.gitignore @@ -24,3 +24,6 @@ css/dist/*.map # jsbuilder output js/dist/**/*.map + +# per-checkout agent instructions +CLAUDE.local.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..896272ef4 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,20 @@ +@AGENTS.md + +