From 9580cbbb63e8fdc98fc856ffa0d9a925627493f4 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 13 Jul 2026 05:54:59 +0000 Subject: [PATCH] Add AGENTS.md with Cursor Cloud setup instructions Co-authored-by: zinoe-1 --- AGENTS.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..350c9ee --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,18 @@ +# AGENTS.md + +## Cursor Cloud specific instructions + +ScratchV is a pure-Python educational compiler (ONNX → RISC-V RV32IM machine code, plus an LLVM-IR path). There is no long-running server or web app; everything runs as CLI tools / pytest. The interactive "course site" and performance "dashboard" are static HTML files opened directly in a browser (`file://` paths), not a served application. + +Standard commands live in the `Makefile`, `README.md`, and `CLAUDE.md` — refer to those rather than duplicating. Notable: `make test`, `make bench`, `make bench-cnn`, `make bench-tinyfive`, `make bench-ci`. + +Non-obvious caveats discovered during setup: + +- **Python**: the VM already has Python 3.12 as `python3`; use it directly (no venv needed). The dependency-refresh update script installs the package and dev tooling. +- **Dev/test tooling is NOT declared in `pyproject.toml`**: `pytest`, `flake8`, `mypy`, `black`, `isort`, `ruff` are installed by the update script, not by `pip install -e .`. `markdown` is only needed for building the docs HTML site (`scripts/build_docs_html.py`). +- **`~/.local/bin` is not on `PATH`**: invoke tools as modules, e.g. `python3 -m pytest`, `python3 -m ruff`, `python3 -m flake8`. +- **`tests/test_simulator.py` has 2 pre-existing failures** (`NameError: name 'load_asm' is not defined` in `scratchv/simulator/tinyfive.py`). CI deliberately skips this file. Run the suite the CI way: `python3 -m pytest tests/ --ignore=tests/test_simulator.py`. +- **`models/` is gitignored** but `models/graph/cnn.onnx` is present in the VM. If it is ever missing, regenerate a minimal model with `python3 scripts/gen_minimal_cnn.py`. +- **External RISC-V toolchains are not installed** (`llc`, `riscv64-*-gcc`, `spike`, `qemu-riscv32`). The core ScratchV native path and the `llvmlite`-based LLVM-IR generation both work without them, but the "LLVM vs ScratchV comparison" step in `make bench-ci` and some Spike/QEMU sim helpers will report `failed`/warnings. This is expected in this environment, not a regression. +- **Lint is best-effort and reports many pre-existing style findings** (ruff/flake8 E501/E741 etc.). Treat the tooling as "runs successfully"; do not attempt to fix pre-existing style issues unless asked. +- The `scratchv` package installs in editable mode, so source edits take effect immediately without reinstalling.