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, 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 allowed_binaries / deny rules ship in the compiled default. Existing installs that explicitly select an older policy keep using that document.

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

Fix: Compare the effective policy to this binary's compiled default, then merge only the new binaries/rules you want:

runtime config validate
runtime config diff policy

Details: Upgrading — the upgrade trap.

Moving capabilities to a shared directory¶

From a legacy Home-local capability directory to an explicit team source:

# before
runtime capability execute my-cap

# after copying the files into /path/to/team-capabilities, add that directory
# to capabilities.sources in the selected external config
runtime capability execute my-cap

See Sharing a Capability Directory.

CI: pinning vs latest¶

Approach	When
Empty `version` (or omit it)	Default — tracks the latest release
a pinned `version:` on `setup-runtime`	Reproducible production pipelines — bump deliberately

After pinning a newer version, use a fresh RUNTIME_HOME so the job starts with only that release's contracts and empty working-state paths.

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.

Operational examples on this site were verified against Runtime 0.9.8. After bootstrap, the version-exact files in Runtime Home win.