# Development environment
The supported setup is the repository's unprivileged VS Code Dev Container. Reopen the checkout in
the container before running the complete gate; it contains the exact Rust and repository tools used
by CI.
## Sources of truth
| Normal Rust toolchain | `rust-toolchain.toml` |
| Minimum Rust version and package version | `Cargo.toml` |
| Rust dependency resolution | `Cargo.lock` |
| Container base and installed tools | `.devcontainer/Dockerfile` |
| Dev Container features | `.devcontainer/devcontainer-lock.json` |
| Node-based file tools | `package-lock.json` |
| Native file-tool checksums | `scripts/install-file-tools.sh` |
CI and release workflows read versions from these files instead of maintaining another prose copy.
Renovate proposes updates; every proposal receives ordinary review and validation.
The Bookworm Dev Container installs an exact `python3-venv` package from Debian's signed apt
repository. Apt verifies package checksums through signed repository metadata rather than a
separate hand-written checksum. The Dockerfile pin is the single version source; Renovate tracks
the Debian 12 package through Repology and requires manual candidate review. Debian's package
metadata lists `3.11.2-1+b1` for both amd64 and arm64 at this pin. Review any candidate against
the pinned image's apt indexes before changing it.
## Complete validation
Run:
```console
./scripts/check-all.sh
```
The gate first creates a temporary isolated Python venv and checks its own pip. This fails quickly
with a Dev Container rebuild hint if `ensurepip` or `python3-venv` is missing. Dev Container
post-create verification and CI's Rust quality job check the same contract before expensive steps.
The probes remove their temporary directories on normal success, failure, and handled interruption.
The script formats repository-owned files before validating them. A successful run covers Rust and
non-Rust formatting, workflow security, repository policy, all targets, Clippy, tests, Rustdoc,
package contents, the offline provider-bootstrap regression, coverage ratchets, MSRV, dependency
policy, offline links, and SemVer checks. Any later edit invalidates the result.
The issue-to-PR sequence and ownership rules are canonical in [`AGENTS.md`](../AGENTS.md). Human and
agent contributors use the same complete gate. The local change-aware planner and VS Code tasks
can shorten iteration on public prose, but do not replace the complete pre-publication run.
## Focused checks
Use focused commands while iterating:
```console
cargo fmt --all -- --check
./scripts/check-files.sh --check
cargo ci-check
cargo ci-policy
cargo ci-clippy
cargo ci-test
cargo ci-doctest
RUSTDOCFLAGS="-D warnings" cargo ci-doc
cargo deny check
actionlint
zizmor .github/workflows
lychee --config lychee.toml --root-dir . --offline './**/*.md'
```
The VS Code task **ComposeLens: Format, lint, and test all** runs the complete workflow. Smaller tasks
mirror the focused commands.
## Tooling behavior
Authored YAML parser fixtures are not generically formatted because malformed and byte-exact input is
part of their test contract. TOML metadata and complete repository YAML are still validated.
Offline Tombi uses the repository's Cargo-manifest schema so an empty cache behaves like an existing
cache. Cargo commands remain the semantic manifest authority. Routine link checks stay offline;
scheduled automation performs rate-limited external checks.
Coverage and SemVer artifacts use repository-specific writable storage below
`$CARGO_TARGET_DIR/check-all/compose-lens`. This avoids another repository's cleanup, read-only global
package locks, or stale generated Rustdoc projects affecting a result.
## Updating the container
When a Dev Container feature changes, regenerate its committed lock with the pinned CLI version from
the repository configuration, review resolved versions and integrity hashes, rebuild, then run the
complete gate. Do not hand-edit a resolved feature reference merely to satisfy a check.
## External conformance
The default container does not mount Docker or Podman sockets, run systemd, or request privileged
mode. Provider and runtime observations require explicit environments and commands defined in
[`conformance/README.md`](../conformance/README.md). Do not widen every editor session's trust boundary
to run an optional evidence capture.
## Agent-assisted verification
Repository model defaults and role overrides live in [`.codex/`](../.codex/); permissions and
workflow ownership remain defined in [`AGENTS.md`](../AGENTS.md). Reload or start a new trusted
project session after updating configuration; an explicit session override can take precedence.
Keep any explicit primary-session override aligned with Sol/xhigh.
Use `./scripts/check-all.sh --check` to run the complete gate without formatting repository-owned
files. The default command (or `--fix`) still formats first. Both modes run the same validation;
ignored caches and build artifacts may change. Verifiers report failures without fixing files,
and the primary agent owns the final complete gate and merges covered by the standing
authorization in [`AGENTS.md`](../AGENTS.md).
The shell-runner regression tests target the Linux Dev Container gate. Agent-configuration checks
remain platform-independent. macOS client compatibility is intended but not verified by CI; the
CI and release validation lanes are Linux-only.