Runtime Home¶

The Runtime Home is the directory holding everything the runtime needs on a machine: configuration, policy, context, capabilities, the specs and cheatsheets that describe the installed binary, the audit log, and a cache.

$HOME/.engineering-runtime/          # Windows: %USERPROFILE%\.engineering-runtime
  version                 the binary version this home was prepared by
  config.yaml             ┐
  policy-config.yaml      │ YOURS — seeded once, never overwritten
  context.yaml            │
  capabilities/           ┘ example capabilities, yours to edit
  specs/                  ┐ THE RUNTIME'S — refreshed to match the binary
  commands/               ┘ on every version change
  logs/audit.log
  cache/

Relocate it entirely with ENGINEERING_RUNTIME_HOME:

export ENGINEERING_RUNTIME_HOME=/tmp/runtime-home
runtime bootstrap

Bootstrap runs before everything¶

Bootstrap is not something you have to remember. It runs before every command — version, audit tail, a provider operation, a capability step. runtime bootstrap exists only so you can see what it did; it never unlocks anything.

A practical consequence: the first command after replacing the binary consumes the refresh. If you run runtime version first, a subsequent runtime bootstrap prints no refresh line. That is success, not failure.

What ships inside the binary¶

The binary embeds four whole directories — configs/, specs/, commands/ and capabilities/. A fresh machine needs the binary and nothing else: no network, no source checkout, no separate asset download.

The two ownership classes¶

This distinction is the one to remember. Everything else about upgrades follows from it.

Class	Paths	Behaviour
User-owned	`config.yaml`, `policy-config.yaml`, `context.yaml`, the capabilities directory	Written only when missing. Never overwritten, never pruned.
Runtime-owned	`specs/`, `commands/`	Rewritten to mirror the binary on a version change. Files the binary no longer ships are deleted.

The reasoning:

User-owned files are your configuration and your engineering knowledge. Destroying them on upgrade would make upgrading dangerous, so the runtime never touches them once they exist.
Runtime-owned files describe the binary. A capability spec or a command cheatsheet that disagrees with the installed binary is worse than none at all — it actively misleads both humans and AI. So they are made to match, every time.

Never keep your own files under specs/ or commands/

They will be deleted on the next version bump. That is by design, not a bug. Put your own material in the capabilities directory, or outside the Runtime Home entirely.

What Bootstrap does, in order¶

1. Resolve home              $ENGINEERING_RUNTIME_HOME, else $HOME/.engineering-runtime
2. Resolve capabilities dir  $RUNTIME_CAPABILITIES_DIR, else <home>/capabilities
3. Create directories        home, logs/, cache/, capabilities dir
4. Seed configs (if missing) config.yaml, policy-config.yaml, context.yaml
5. Seed capabilities         every embedded example (if missing)
6. Read <home>/version       "" when absent
7. If recorded != binary:    refresh specs/ and commands/, prune, record version

Steps 4 and 5 run on every invocation, not only on a version change. That is why a release which adds an example capability delivers it on upgrade, while never touching one you have edited.

Step 7 is the only version-gated part.

The version marker¶

<home>/version holds the version of the binary that last prepared the home.

Comparison	Result
Equal to the running binary	No refresh — ordinary commands don't rewrite files
Different	Refresh. Any difference, so a downgrade refreshes back down
Absent	Refresh. Covers a brand-new home and a home created before version tracking

Forcing a refresh without a version change — the standard fix if you've edited specs/ or commands/ locally and want the shipped copies back:

rm ~/.engineering-runtime/version && runtime bootstrap

Pruning is confined¶

The refresh collects the files the binary ships for a tree, writes them all, then deletes anything else inside that tree's own directory. Pruning can never reach config.yaml, the capabilities directory, logs/, or anything else outside specs/ and commands/ — including unrelated files you have left in the Runtime Home.

Relocating capabilities¶

RUNTIME_CAPABILITIES_DIR moves the capabilities directory out of the Runtime Home entirely. It is both where examples are seeded and where capability names are resolved, so a team or a CI fleet can point at one shared, version-controlled directory without relocating runtime state that has nothing to do with capabilities.

export RUNTIME_CAPABILITIES_DIR=~/work/team-capabilities
runtime bootstrap
runtime capability execute github/repo-health --input repository=cli/cli

When the override is set, no capabilities/ directory is created inside the Runtime Home at all. See Sharing a Capability Directory.

Inspecting a home¶

runtime bootstrap --output json     # paths, version transition, seeded/refreshed/pruned files
runtime config validate             # resolved locations + live auth and binary checks
ls -R "${ENGINEERING_RUNTIME_HOME:-$HOME/.engineering-runtime}"

runtime bootstrap --output json reports the home and capabilities paths, whether the home was just created, the version transition, and exactly which files were seeded, refreshed and pruned on that run.