diff --git a/README.md b/README.md
index 4164b63..58c4c83 100644
--- a/README.md
+++ b/README.md
@@ -165,3 +165,14 @@ disinto/
 - **Self-improving** — when Claude fixes something new, the lesson is appended to best-practices for next time
 - **Project-agnostic** — all project-specific values (repo, paths, CI IDs) come from `.env`, not hardcoded scripts
 
+### Runtime constraints
+
+Disinto is intentionally opinionated about its own runtime. These are hard constraints, not preferences:
+
+- **Debian + GNU userland** — all scripts target Debian with standard GNU tools (`bash`, `awk`, `sed`, `date`, `timeout`). No portability shims for macOS or BSD.
+- **Shell and binaries only** — disinto itself has no Python, Node.js, or other interpreted runtime dependencies. Every agent is a bash script. If you need a helper, write it in bash or use an existing binary.
+- **Few, powerful dependencies** — the only required non-standard tools are `jq`, `curl`, `git`, `tmux`, and `psql`. Adding a new disinto-level dependency requires a strong justification.
+- **Node.js and Foundry are target-project dependencies** — if your target repo uses Node or Solidity, install those on the host. They are not part of disinto's core and must not be assumed present in disinto scripts.
+
+The goal: any Debian machine with the prerequisites listed above can run disinto. Keep it that way.
+