Agent Notes

Repository Context

Runtime and front ends live under src/; unit tests under Tests/; executables build to build/bin/ via CMake.
Pascal/REA compiler logic is concentrated in src/compiler/compiler.c; many globals track compile state, so save/restore helpers are common.
When git add fails with permission errors or .git/index.lock, rerun with elevation; the workspace sometimes lives on file systems that gate writes.

Configure with cmake -S . -B build [-DSDL=ON] [-DBUILD_DASCAL=ON], then cmake --build build.
Use Tests/run_all_tests; set RUN_SDL=1 or RUN_NET_TESTS=1 as needed. Prefer targeted scripts in Tests/ for quicker iteration.
Library conformance lives under Tests/libs/. Each front end has its own harness; the Rea suite (Tests/libs/rea/run_tests.py) spins up an HTTP helper, inspects optional extended built-ins (yyjson, etc.), and exports REA_TEST_EXT_BUILTINS/REA_TEST_HAS_YYJSON so JSON checks are skipped when support is absent.
Scope validation suites live in Tests/scope_verify/ (clike, pascal, rea). The harnesses are manifest-driven and support --only, --list, --seed, and --cmd overrides. Rea's runner (Tests/scope_verify/rea/rea_scope_test_harness.py) materialises fixtures via --update and records reports under Tests/scope_verify/rea/out/.
Test manifests (e.g., Tests/scope_verify/rea/tests/manifest.json) are generated through the corresponding build_manifest.py; regenerate them when adding or editing cases to keep fixtures in sync.
For exsh tests that don't include PSCAL extenstions, the output should always be identical to what the bash shell would produce
For exsh shellbench (https://github.com/shellspec/shellbench) is used as both benchmarking and functionality verification
Appropriate tests should always be run. It is NEVER appropriate not to test. At the very least you should verify that modified code compiles

C11 style: 4-space indent, braces on same line, camelCase for functions, uppercase snake for macros.
Concurrency is the default design target. Do not "fix" races by serializing whole applets/subsystems with global locks unless explicitly requested; prefer per-instance/per-session isolation and thread-safe state ownership.
Many compiler helpers rely on implicit global state; when adding new stacks (like the vtable tracker), ensure push/pop happen on every exit path.
Keep allocations paired with frees; leak auditors assume matcher functions like freeVTableClassList exist.
When adding VM builtins, append them to the end of the dispatch tables/registration arrays so legacy builtin IDs remain stable. Never insert new entries mid-table—shifting established builtin IDs breaks existing bytecode, so this must never happen.

Always read existing globals before introducing new ones—regressions often come from missing reset logic during module/unit compiles.
Tests are slow; when editing the compiler, run at least the relevant front-end suite prior to broader sweeps.
Document any env vars you touch (SDL_VIDEODRIVER, RUN_SDL, etc.) in commits/PRs; future agents look here for quick bootstrapping.
Binaries tend to have both a --dump-ast-json and --dump-bytecode options which can provide substantial clues as to what is going on in the AST building and compilation portions of the code when debugging.
Commit early and often—small, frequent commits keep iPadOS and desktop work in sync and avoid multi-thousand-file diffs that are hard to review or push.