Skip to main content
Upgrading Substrate involves three coordinated steps: pulling and rebuilding the binary, refreshing the agent skill so it matches the new binary, and verifying that your boards still load cleanly under the updated schema. Each step is quick, and skipping any one of them leaves your installation in a state where things can fail silently.

​
Upgrade the Binary

While Substrate is pre-release (v0.7.0), upgrade by pulling and rebuilding the clone you linked globally.
The global link keeps pointing at the same build output, so the substrate command picks up the new version immediately — no relink required. Confirm the version with:
Once the package is published to npm, npx @diegoferreyra/substrate will resolve the published version and the manual link step goes away entirely.

​
Refresh the Agent Skill

The skill installed at ~/.claude/skills/substrate is stamped with the binary version it came from, so the two cannot silently drift. Check and refresh it with:
Use --check in CI pipelines or as a quick pre-flight — it reports drift and exits non-zero without writing anything. A refresh is idempotent: re-running it against a current install reports “already current”.
Upgrade the binary and the skill together. A skill that describes tools or conventions the binary no longer supports is worse than no skill — the agent will follow instructions that quietly fail.
substrate diagnose also reports skill drift, so it doubles as a post-upgrade confidence check.

​
Verify Boards and Schema

config.json carries a schema_version, and the database runs its own migrations automatically when opened by a newer binary. Board files are different — they are read fresh on every call and are not migrated automatically. A board file that no longer matches the current schema fails loudly with a substrate_corrupt error that names the offending file. After any upgrade, run both validation commands:
1

Run substrate validate

Loads every board and reports any files that fail the current schema. Fix or remove flagged files before continuing.
2

Run substrate diagnose

Confirms the environment, database, server, and skill are all consistent with the new binary version.
Substrate is pre-1.0. Board and schema shapes can still change between versions. The CHANGELOG is where those changes are recorded — review it before upgrading in a team environment.