Agent environment bootstrap

An agent environment's install step MUST be a call to the repository's install task and nothing else.

mise install is the one command, on every platform. A bootstrap that installs packages itself is a second, invisible copy of the repository's setup that nobody edits when the real one changes — and the first symptom is an agent that cannot run the tests it was asked to fix.

mise trust && mise install

Bootstrap configuration held outside the repository MUST contain no logic beyond that call.

Some platforms keep the setup script in a dashboard rather than in the tree. Anything written there is invisible to review, to git log, and to every agent reading the repository. Keep it to the install line so that the part which can drift is the part that never changes.

A repository MUST record which agent platforms it supports in AGENTS.md.

An agent arriving through a platform nobody configured will improvise a setup, succeed unevenly, and leave no trace of what it did. Naming the supported platforms makes an unsupported one an explicit gap rather than a silent one.

AGENTS.md MUST be the single agent entry point, and a platform-specific instruction file MUST point at it rather than restating its content.

CLAUDE.md, .cursor/rules, and their equivalents are per-vendor filenames for one idea. Copying guidance into each produces three documents that disagree within a month. A one-line pointer cannot disagree with anything.

# CLAUDE.md
See AGENTS.md. It is the entry point for every agent in this repository.

An agent environment MUST NOT hold production credentials.

Give it preview-scoped or read-only credentials, resolved through fnox from a non-production vault. Platforms differ in how well they protect these — at least one keeps environment variables visible to anyone who can edit the environment, with no dedicated secrets store — so the safe assumption is that anything given to an agent environment is disclosed.

Bootstrap MUST be idempotent.

Platforms cache the result: a snapshot, a cached filesystem, a warm image. A bootstrap that only works on a clean container, or that appends to a file each time it runs, produces environments that differ from each other in ways nobody can reproduce.

Bootstrap MUST succeed under the platform's default network policy, or the hosts it needs MUST be recorded in AGENTS.md.

Cloud agents run behind restricted egress. A bootstrap that quietly needs a private registry fails as a timeout several minutes in, which reads as a broken platform rather than a missing allowlist entry.

A supported platform's bootstrap MUST be verified by running it before the platform is listed.

Configuration that has never been executed is a guess. Start one session on the platform, run mise run lint and mise run test inside it, and only then add it to the list.

A platform whose bootstrap has stopped working MUST be removed from the supported list.

Removing it is honest and takes a line; leaving it listed sends the next agent into a container that cannot build, and it will spend its round diagnosing the environment rather than the ticket.