diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..8de5dfb
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,38 @@
+# AGENTS.md
+
+## Cursor Cloud specific instructions
+
+This is a pure Python library with no external services, databases, or Docker dependencies.
+
+### Running commands
+
+All dev commands require `python3` (not `python`) and `$HOME/.local/bin` on PATH:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+### Key commands (via Makefile)
+
+| Task | Command |
+|------|---------|
+| Lint | `python3 -m ruff check src/ tests/` |
+| Typecheck | `python3 -m mypy src/` |
+| Tests | `python3 -m pytest tests/ -v --tb=short` |
+| All checks | `make all` (requires PATH fix above) |
+
+### Running examples
+
+Examples must be run from the repo root with `PYTHONPATH=src`:
+
+```bash
+PYTHONPATH=src python3 examples/python/real_world_logistics_planning.py
+PYTHONPATH=src python3 examples/python/constraint_based_scheduling.py
+PYTHONPATH=src python3 examples/python/mcp_usage.py
+```
+
+### Known issues
+
+- The `python-sat` optional extra (`[sat]`) is not installable from PyPI (no stable release >=1.8 exists). The built-in `dpll_sat` engine works without it.
+- `examples/python/llm_verified_reasoning.py` has a bug in its local fallback: uses `'A*'` instead of `'astar'` as engine name.
+- mypy emits harmless warnings about `pyproject.toml` per-module config flags — these are non-blocking.