Upgrading

One command shows what is behind and brings it up to date:

e11 upgrade

  component        installed       latest
  Foundry CLI      2.5.0 (npx)     2.5.0
  Foundry skills   2.5.0           2.5.0
  Alloy CLI + MCP  1.7.0           1.9.2   ↑
  E11 knowledge    1.9.0           1.9.2   ↑

Row	What it is	What an upgrade does
Foundry CLI	The e11 you are running, and how it was launched	Installs the newer CLI where this one lives, then hands the rest to it
Foundry skills	The Toolkit version .foundry/project.toml pins	Re-pins and re-vends the editor skills through the same converge as e11 init
Alloy CLI + MCP	The alloy command this repo resolves, and the MCP entry each editor file pins	Reinstalls Alloy where it lives and refreshes the MCP entries
E11 knowledge	The Engineering11 knowledge version .alloy/corpus.lock pins	Moves the pin, which changes a committed file

On a terminal, one question upgrades the code rows. The E11 knowledge row has its own question, default no, because it changes .alloy/corpus.lock for the whole team; e11 upgrade --only knowledge moves it by name. e11 upgrade --check writes nothing and exits 0 when current, 1 when something is behind, 2 when the registry cannot say. A checkout without a knowledge base shows only the two Foundry rows.

Once a day, a Foundry command run in a repository with a knowledge base mentions a newer Alloy in one line. e11 upgrade is the answer to that line.

Init on an existing checkout

e11 init on a checkout that already answered the knowledge question converges it, then prints <project> is set up (knowledge: <answer>). Checking versions… and the same table. On a terminal, Bring everything up to date? applies the code rows. With --yes, or without a terminal, init only shows the table and Re-run e11 upgrade --yes to apply.; the table never changes init's exit code.

A checkout from before the knowledge question is read from its files on its next init: a lock naming the Engineering11 knowledge reads as e11, any other lock entry as other, a bare .alloy/ as own, nothing as none. Init writes that answer back to .foundry/project.toml and never asks.

Teammate on an older CLI

Saving the knowledge answer adds a [knowledge] table to .foundry/project.toml. An e11 from 2.4.0 or earlier refuses the file on every command:

…/.foundry/project.toml is not a project file this release understands

That teammate runs one command:

npm install -g @engineering11/e11-foundry@latest

An npx user runs npx @engineering11/e11-foundry@latest init instead. This happens once: the CLIs from this release on read the committed minimum_cli_version first, so a later addition to the file is refused with this CLI is X; … requires at least Y, which names the version to install.

Coming from 1.x

For a fresh checkout, follow Get started. Use this checklist when upgrading a checkout with older operational state.

Install the required CLI

npm install -g @engineering11/e11-foundry@2.0.0
e11 --version

A CLI below minimum_cli_version refuses normal operation with CliVersionTooOld. Install at least the version your project file requires.

Register the checkout

e11 migrate identity bootstrap -d <checkout>

Run once for each checkout. The command creates the local pointer and workspace record. A checkout without earlier runs follows the fresh setup path.

Move existing operational state

e11 migrate storage adopt --workspace <id> -d <checkout>

Use the workspace ID from bootstrap. Adopt selects generation 2 when no legacy run needs relocation. If adopt names existing runs, import their state.

e11 migrate storage import --workspace <id> -d <checkout>

Import relocates the checkout’s runs in every state on this machine. The single-machine path needs no cutover ID or cohort roster. Repeat import after an interrupted relocation to recover.

Pin the Toolkit

e11 migrate toolkit install -d <checkout>

For a local release archive, add --from <tarball>. The command verifies the Toolkit and records its version and digest.

Review and commit shared inputs

Review .foundry/project.toml, .foundry/pricing.json, and .foundry/profiles.toml. Confirm identity, publication root, rates, and meaningful acceptance commands. Init refuses a profile with no acceptance commands.

e11 init
e11 doctor
git add .foundry/project.toml .foundry/pricing.json .foundry/profiles.toml .gitignore
git commit -m "chore: upgrade Foundry inputs"

Resolve fix rows and review price differences. Init removes retired editor skills according to the pinned Toolkit’s removals list.

Select the initiative and import an older board

e11 initiative use <slug>
e11 initiative board import --legacy <path> --title <text>

Board import is for an existing legacy status file. Create a new board with e11 board create for a new initiative.

Update saved prompts

Retired name	Use
e11-platform	e11-knowledge
e11-review-adversarial-general	e11-review
e11-review-edge-case-hunter	e11-review
e11-review-verification-gap	e11-review
e11-review-reachability	e11-review
e11-review-alloy-auditor	e11-review
e11-editorial-review-prose	e11-review
e11-editorial-review-structure	e11-review
e11-sprint-planning	e11-sprint
e11-sprint-status	e11-sprint
e11-check-implementation-readiness	e11-sprint
e11-dev-story	e11-dev-flow
e11-create-story	e11-dev-flow
e11-create-prd	e11-prd
e11-edit-prd	e11-prd
e11-validate-prd	e11-prd
e11-create-ux-design	e11-ux
e11-create-architecture	e11-architecture
e11-create-product-brief	e11-product-brief
e11-bootstrap-wizard	e11-scaffold
e11-scaffold-app	e11-scaffold
e11-scaffold-backend	e11-scaffold
e11-scaffold-frontend-app	e11-scaffold
e11-scaffold-microservice	e11-scaffold
e11-scaffold-microservice-package	e11-scaffold
e11-scaffold-sdk-backend	e11-scaffold
e11-scaffold-sdk-frontend	e11-scaffold
e11-scaffold-service	e11-scaffold

The former SM role maps to board planning and status through e11-sprint. The former QA role maps to e11-qa-generate-e2e-tests and e11-code-review. Solo development uses e11-spec-flow and e11-dev-flow.

Review translated overrides

Older YAML customizations use TOML overrides now. Review the translation report and each resulting file. Plain arrays append, including principles. Convert unsupported prompts to supported menu entries or persistent facts. Commit team overrides and keep personal files ignored.

Customization explains resolution. Legacy engine compatibility explains old run access.

Coordinated cutover procedures