docs: `foundryup` recommendation can install a version different from the repository-pinned Foundry toolchain

[mssystem1]

Summary

The repository pins Foundry to a specific version in .mise.toml for deterministic builds, ABI/storage snapshots, and semver-lock hashes.

However, the README currently recommends running:

foundryup

when semver-lock fails because of a Foundry version mismatch.

foundryup normally updates Foundry independently of the repository's .mise.toml pin. This can leave contributors on a different Foundry version from the one explicitly required by the repository and CI.

The recovery instruction can therefore make the original version-mismatch problem worse rather than resolving it.

Affected Files

• README.md
• .mise.toml

Current Behavior

.mise.toml explicitly states that the repository pins tooling so contributors and CI execute builds, tests, snapshots, and semver-lock generation with byte-identical tooling.

The current pin is:

[tools]
foundry = "1.5.1"

The README, however, says that if semver-lock still fails because of a Foundry version mismatch, contributors should run:

foundryup
just semver-lock

This does not guarantee installation of Foundry 1.5.1.

Why This Is a Problem

A contributor can follow the README exactly and still end up using a toolchain different from CI.

Example flow:

1. Contributor clones the repository.
2. Contributor has an older or newer Foundry version.
3. just semver-lock fails.
4. Contributor follows the documented recovery instructions.
5. foundryup installs the current Foundry release.
6. The installed version is not necessarily the repository-pinned 1.5.1.
7. Generated semver-lock hashes or snapshots can still differ from CI.

This contradicts the reproducibility requirement documented in .mise.toml.

Expected Behavior

The README should direct contributors to install the exact repository-pinned toolchain.

For example:

mise install
mise exec -- just semver-lock

or otherwise explicitly install the same Foundry version used by CI.

Suggested Fix

Replace:

If CI still rejects it (Foundry version mismatch), update your local Foundry first:

```bash
foundryup
just semver-lock

with something similar to:

```markdown
If CI still rejects it because of a Foundry version mismatch, install the repository-pinned toolchain:

```bash
mise install
mise exec -- just semver-lock

The Foundry version is pinned in .mise.toml and should match CI.

## Additional Improvement

The setup section currently also says:

```bash
just install-foundry

Consider making mise install the canonical setup path if .mise.toml is intended to be the authoritative source of tool versions.

Alternatively, just install-foundry could explicitly install the version defined by .mise.toml.

Impact

This is primarily a developer-experience and build-reproducibility issue.

It can cause:

• unnecessary CI failures;
• semver-lock hash mismatches;
• snapshot differences;
• contributors regenerating artifacts with unsupported tooling;
• confusion when following the documented remediation steps.

Environment

Repository:

base/contracts

Branch:

main

Affected documentation:

README.md

Toolchain definition:

.mise.toml