Set up Cloud Agent dev environment + AGENTS.md run notes

[ibuilder]

What & why

Sets up the Cloud Agent development environment for Massing and documents how to run it. The only
tracked change is a new AGENTS.md (force-added — the repo gitignores it to prevent accidental
git add -A publishes, but explicitly permits git add -f when committing it deliberately) with a
## Cursor Cloud specific instructions section. Dependency installation is handled by the environment
update script (submitted separately for approval), not by code changes.

What the environment provides

• Node 24 via nvm (repo requires node >=24; Node 18 breaks the web build). Note: /exec-daemon/node
  (v22) shadows nvm on PATH, so web commands must prepend Node 24 — documented in AGENTS.md.
• Web deps via npm install (workspace installs apps/web; predev copies web-ifc WASM).
• API/Python deps into the user site (~/.local): services/api/requirements.lock (runtime, hash-pinned)
  and requirements-dev.txt (ruff/pytest/httpx/…). services/data deps are a subset of the lock.

Services (dev, from source)

Service	Path	Command	Port
Web (Vite + TS)	apps/web	npm run dev	5173
API (FastAPI, bundles services/data)	services/api	uvicorn aec_api.main:app --reload	8000

Dev uses SQLite + local filesystem storage — no Postgres/MinIO/Docker required. A non-obvious gotcha
(documented in AGENTS.md): authoring endpoints need a writable IFC_DIR/STORAGE_DIR, otherwise they
500 with PermissionError: /app (the defaults are in-container paths).

Verification

• Web: npm run typecheck clean · npm run lint clean · npx vitest run → 1651/1651 passed · dev server on :5173.
• API: python -m ruff check src/ ../data/src/ clean (the CI invocation) · test_api.py + test_empty_project.py pass · uvicorn on :8000 · GET /health ok.
• End-to-end hello-world: created a new Office bay model from scratch → API authored real IFC → reconverted to Fragments (publish state: done, model.frag, v1) → viewer loaded the 3D model → selecting a wall showed its IFC GlobalId + Pset_WallCommon.

New-model template picker
Authored Office-bay model loaded in the 3D viewer
Selected wall element with IFC GlobalId + property sets

Checklist

• Backend: cd services/api && python -m ruff check src/ ../data/src/ clean
• Backend: sample test_*.py pass (test_api, test_empty_project)
• Web: npm run typecheck && npm run lint clean; npx vitest run green (Node 24)
• CHANGELOG.md / roadmap — n/a (no product code change; docs + env only)
• No secrets committed

_{To show artifacts inline, enable in settings.}

  

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: aa12f9fb-68aa-40f1-b58c-6db9c21dd6b3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}