From 11e4c4cb9a88921d177c9d97df0e6cf582839403 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 6 Jul 2026 03:22:33 +0000 Subject: [PATCH] docs: add Cursor Cloud environment setup notes to AGENTS.md Co-authored-by: allenl329 --- AGENTS.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 7649447bc..5d47ed876 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,3 +7,21 @@ It contains routing rules that determine your first action based on what the use Skipping it WILL cause you to take the wrong action. There are no instructions in this file. All instructions are in AGENT_GUIDE.md. + +## Cursor Cloud specific instructions + +These notes cover non-obvious environment caveats. Standard usage lives in `README.md`, the `Makefile`, and `AGENT_GUIDE.md`. + +### Python invocation +- Only `python3` exists on this VM — there is **no `python` executable**. The `Makefile` targets (`make setup`, `make lint`, `make demo`, `make test`) call `python` and will fail on the `python …` lines. Run the underlying commands with `python3` directly (e.g. `python3 render_demo.py`, `python3 -m pytest tests/`). +- Python deps install into the user site; console scripts land in `~/.local/bin`, which is **not on PATH**. Invoke tools as modules instead of by name: `python3 -m pytest …` (not `pytest`). + +### Running / verifying the app (zero-key path) +- The core deliverable is a rendered video. The fastest end-to-end proof needs no API keys: `python3 render_demo.py world-in-numbers` renders a real 1920×1080 H.264+AAC MP4 into `projects/demos/renders/` via Remotion. `python3 render_demo.py --list` shows all demos. +- Preflight / capability discovery: `python3 -c "from tools.tool_registry import registry; import json; registry.discover(); print(json.dumps(registry.provider_menu_summary(), indent=2))"`. +- All three composition runtimes are available here (ffmpeg, remotion, hyperframes). +- **HyperFrames renders use headless Chrome and `/dev/shm` is only 64 MB on this VM (Chrome wants ≥256 MB).** `hyperframes doctor` flags this; large/complex HyperFrames renders may need a bigger shm or Chrome shm-disable flags. The Remotion path is unaffected. + +### Known pre-existing issues (not environment problems) +- `make lint` references `tools/composition_validator.py`, which does not exist in the repo, so that target fails. The other three files it lists compile fine: `python3 -m py_compile tools/base_tool.py tools/tool_registry.py tools/cost_tracker.py`. +- Contract tests: 257 pass, 6 skip, 2 fail on a clean checkout — `test_registry_catalog_views` (a `doubao` TTS provider was added without updating the expected set) and `test_planning_skill_mentions_runtime_contract[character-animation]` (pipeline skill missing runtime-contract text). Both are content/test drift, unrelated to setup.