# 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 ```bash pixi run test # build, then every test (node --test against dist/, the corpus pipeline's Python tests included) pixi run ci # the gate: every test, and no Mojo program of ours failing ``` Without pixi (a sandbox with only Node and Python): ```bash tsc -p tsconfig.json && node --test tests/*.test.mjs python3 scripts/mojo/corpus.py status --strict ``` **Finish every change with the gate green.** 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 full suite takes about two minutes. While iterating, build and run one file: `tsc -p tsconfig.json && node --test tests/state.test.mjs`. ## Hard rules 1. **Do not edit generated files by hand.** `src/mojo/generated/*` and `quarto/_extensions/pplus/syntax/mojo.xml` come from the corpus pipeline (`pixi run mojo-emit`, `mojo-status`, `play`). `quarto/_extensions/pplus/pplus-views.css` comes from `styles.css`, and `pplus-hw.css` and `course/*.css` beside it from `styles/course/` (`pixi run quarto-css`; a test fails while they are out of date, so run it after changing a rule the views use). `mojo/corpus/` comes from `mojo-harvest`. `mojo/golden/` holds godbolt's answers and comes only from `mojo-verify`. 2. **Do not edit a `.mojo` file's text unless the task needs it.** A stored godbolt answer is keyed by the whole source, header comments included, so any edit (even to a comment) makes the program unverified until it is asked again on the network. If you add or change one, say in your summary that it needs `pixi run mojo-verify-item '/'`. 3. **Never claim Mojo compiles, runs, or prints something without the real compiler's answer.** Mojo is pinned to 1.1.0. The checker may never report an error on a program the compiler accepts, and the interpreter must print exactly what godbolt printed or decline; `tests/mojo-check.test.mjs` and `tests/mojo-run.test.mjs` hold them to that. Every Mojo construct you write into the app must pass `checkMojo`, and every standard-library name must exist in `src/mojo/generated/stdlib.ts` or `types.ts`. 4. **No new dependencies.** TypeScript is the only npm package. There is no bundler, no framework, and no runtime dependency; the corpus pipeline is Python's standard library only. CodeMirror is vendored as one built module (`src/vendor/`), rebuilt only by `scripts/vendor/codemirror.sh`. 5. **You have no network** in most sandboxes. Godbolt (`mojo-verify`, Compile & run) and GitHub (`mojo-harvest`, `mojo-fetch`) need one. Never fake their results; leave those steps to the owner and list them. 6. **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 `