- [ ] **Pick the primary runtime and version.**
→ *Decide your stack (e.g. **Java 21 LTS** or **Python 3.12.x**). Record in `README` → “Execution Environment,” including **Why this version** (LTS, library support, tooling).*
- [ ] **Question:** Do you need a version matrix?
→ *If multiple modules differ (e.g. service A on Java 21, tool on Python 3.11), list each module’s runtime in `/docs/env_matrix.md`.*
- [ ] **Standardize install method (cross-OS).**
→ *Choose one per runtime and document it in `/docs/install.md`:
**Java**: SDKMAN!, Homebrew/apt/choco, vendor SDK (Temurin/Oracle).
**Python**: pyenv/Windows Store, system package manager, official installers.*
- [ ] **Pin versions in the repo.**
→ *Commit files that declare versions:
**Java**: Gradle/Maven **toolchains** with `source/target=XX`, `--release` set; note JDK vendor if required.
**Python**: `.python-version` (pyenv) or `pyproject.toml`/`runtime.txt`; add `requires-python = ">=3.12,<3.13"` if using pyproject.*
- [ ] **Question:** How will tools pick the right runtime automatically?
→ *Document IDE auto-detection (e.g. IntelliJ uses Gradle toolchain; Poetry/uv uses `pyproject.toml`). Add steps in `/docs/install.md`.*
- [ ] **Add quick version checks.**
→ *In `README` add commands to confirm setup:
`java -version` / `./gradlew -v` | `python --version` / `pip list` or `poetry --version`.*
- [ ] **Question:** What about OS-specific quirks?
→ *Note any Windows/macOS/Linux caveats (PATH, certificates, xcode-select, build tools). Add fixes/workarounds in `/docs/os_notes.md`.*
- [ ] **Disaster recovery / new machine.**
→ *Provide a 5-minute “from zero” script or commands that install the chosen JDK/Python and verify with the project (store in `/scripts/setup_env.*`).*
- [ ] **Change control for versions.**
→ *When upgrading JDK/Python, open an issue `env-upgrade: <runtime> <version>`, run tests locally & in CI, and update all pinned files and `/docs/install.md`.*