# eve-tinker contributor guide

This repository has two runtimes: Eve on the pinned project-local Node.js 24.18.1 and
Tinker training on Python 3.11+. The system Node may be 22; `pnpm install` owns Eve's
runtime. Keep their responsibilities separate.

- Read the installed Eve documentation under `node_modules/eve/docs/` before changing
  framework integration code. Use <https://eve.dev/docs> only when package docs are not
  installed.
- The Eve agent calls the local bridge in `bridge/server.py`. The bridge uses Tinker's
  native sampler with the same no-thinking renderer as training. Do not point Eve at the
  hosted OpenAI endpoint: that endpoint fixes Qwen 3.5 to the thinking template.
- The Python runtime owns native sampling, training, evaluation, checkpoint promotion,
  and the loopback bridge. Eve never needs the Tinker key.
- `EVE_RECIPE` must select the same recipe across data, instructions, checkpoint, bridge,
  smoke, and eval surfaces. Never serve one recipe's adapter under another recipe's
  instructions.
- Never copy `TINKER_API_KEY` into the repository, `.tinker/`, artifacts, logs, or tests.
  Integration commands receive it through the process environment.
- `.tinker/<recipe-id>.json` and `artifacts/` are local receipts. They are ignored and
  written with mode `0600`.
- The Python environment lives at `.generated/venv` with `.venv` as a compatibility
  symlink. Eve 0.29.5 skips `.generated` in development snapshots but does not skip a
  physical `.venv`; do not replace the symlink with a five-gigabyte copied environment.
- The hidden test split opens only after a candidate passes the validation gate. Do not
  weaken that boundary to make a run look successful.
- Keep each recipe closed and deterministic. A model response is correct only when it
  matches the selected recipe's exact canonical JSON.
- New examples need a distinct agent behavior, deterministic split isolation,
  recipe-specific target validation, generated Eve fixtures, and explicit documentation
  of whether a trained result actually exists.
- Run `pnpm check`, `pnpm build`, and the credentialed smoke/eval path before reporting an
  integration as working.