Migration Guides¶

Engineering Runtime upgrades are binary replacements. There is no database migration and no daemon. Most "migrations" are about policy and capabilities staying compatible with a new surface.

Upgrading the binary¶

Follow Upgrading:

Download and verify the new archive
Replace runtime on PATH
Run any command (Bootstrap refreshes specs/ and commands/)
Run runtime config validate

What survives¶

Your config.yaml, policy-config.yaml, context.yaml, and existing capabilities are never overwritten.

What refreshes¶

specs/ and commands/ are rewritten to match the new binary. Do not store your own files there.

The upgrade trap: stale policy¶

New default allowed_binaries / deny rules ship in the seed policy-config.yaml. Existing installs keep their old file.

Symptom: runtime command run helm … denied even though the release notes say helm is allowed.

Fix: Compare your policy to the seed (from a throwaway Home or the release notes), then merge the new binaries/rules you want. Diagnose with:

runtime config validate

Details: Upgrading — the upgrade trap.

Moving capabilities to a shared directory¶

From Home-local capabilities to a team store:

# before
runtime capability execute my-cap

# after
export RUNTIME_CAPABILITIES_DIR=/path/to/team-capabilities
# copy or move your .md files into that tree
runtime capability execute my-cap

See Sharing a Capability Directory.

CI: pinning vs latest¶

Approach	When
`version: v0.5.2` on `setup-runtime`	Reproducible production pipelines
Empty `version` (latest)	Smoke / demo jobs that track releases

After pinning a newer version, wipe the job Home (or use a fresh ENGINEERING_RUNTIME_HOME) so Bootstrap re-seeds cleanly.

Provider surface changes¶

Providers ship compiled into the binary. A new operation arrives only by installing a new runtime version. Capabilities that named a removed or renamed operation fail at capability validate — fix the capability, do not bypass with raw CLIs.

When a new Runtime Provider appears in a release:

Read its page under Providers
Enable auth if required (Authentication)
Adjust policy only if you need denies from day one
Prefer new provider operations over equivalent command run calls

From ad-hoc scripts to capabilities¶

Before	After
Shell script calling `gh` / `kubectl`	Markdown capability with `provider:` / `binary:` steps
Credentials in the script	Platform login + `runtime auth` / env tokens
No audit	`runtime audit tail` after execute

Authoring: Capabilities.