# AGENTS.md Instructions for coding agents (and people) changing Programming+. Read this first, then the [README](README.md) for what the app is and where things are. When this file and a task's instructions disagree, the task wins; say so in your summary. ## Build, test, and the gate The engine core (the languages, translators, Mojo checker and interpreter, prover, fuzzer, machine model and the Mojo corpus) is **pplus-core**, the git submodule `core/`, with its own rules in [core/AGENTS.md](core/AGENTS.md). This file is for the site. ```bash pixi run test # build core, then the site, then every test of the site pixi run core-test # core's own tests, at the pinned commit ``` Without pixi (a sandbox with only Node and Python): ```bash npm install && npm test (cd core && node --test tests/*.test.mjs && python3 scripts/mojo/corpus.py status --strict) ``` **Finish every change with the gate green**, both commands. The baseline passes completely; there is no known failure to work around. If a test fails, fix the cause or stop and report it. Do not skip, loosen, or delete a test to get green. The site's suite takes under a minute. While iterating, build and run one file: `npm run build && node --test tests/state.test.mjs`. ## Hard rules 1. **A change to what programs mean belongs in core.** A translator, the checker, the interpreter, the prover, the fuzzer, the machine model, the catalog's problems, the Mojo corpus: change them in pplus-core under its rules (its own commit, its own gate), then move the `core` pointer here in a commit that says what it brings. Never edit `core/` from a site change without that. The site imports core only as `#core/.js` (the import map in `index.html`, `imports` in `package.json`), from its built `core/dist/`. 2. **Do not edit generated files by hand.** `quarto/_extensions/pplus/pplus-views.css` comes from `styles.css`, `pplus-hw.css` and `course/*.css` beside it from `styles/course/`, and `syntax/mojo.xml` from core's `core/library/syntax/mojo.xml` (`pixi run quarto-css`; a test fails while they are out of date, so run it after changing a rule the views use). Core's generated files are listed in its AGENTS.md. 3. **Never claim Mojo compiles, runs, or prints something without the real compiler's answer.** Mojo is pinned to 1.1.0 by core. What the app shows about Mojo comes from core's checker and interpreter and from godbolt's answers (stored in `core/library/mojo/golden/`, or asked live by Compile & run); the site never invents a verdict, and every Mojo construct written into the app must pass `checkMojo`. 4. **Never show "proved" for something that is not a proof.** The badges and verdicts are in [core/docs/trust.md](core/docs/trust.md); the site shows what core decided and does not soften or upgrade it. 5. **No new dependencies.** TypeScript is the only npm package. There is no bundler, no framework, and no runtime dependency. CodeMirror is vendored as one built module (`src/vendor/`), rebuilt only by `scripts/vendor/codemirror.sh`. 6. **You have no network** in most sandboxes. Godbolt (Compile & run) needs one, and so do core's network tasks. Never fake their results; leave those steps to the owner and list them. 7. **Keep the workspace working while you change it.** Code panes are always the CodeMirror editor (`Editor` in `src/ui/editor.ts`, over the vendored `src/vendor/codemirror.js`), never a `