> ## Documentation Index
> Fetch the complete documentation index at: https://docs.substrate.42.pe/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade Substrate: Binary, Agent Skill, and Board Files

> How to pull and rebuild the Substrate binary, refresh the agent skill so it matches, and confirm your boards load cleanly after an upgrade.

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.

```sh theme={null}
git pull
pnpm install
pnpm build
```

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:

```sh theme={null}
substrate --help     # the first line names the version
```

<Info>
  Once the package is published to npm, `npx @diegoferreyra/substrate` will resolve the published version and the manual link step goes away entirely.
</Info>

## 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:

```sh theme={null}
substrate install-skill --check   # report drift, exit non-zero, write nothing
substrate install-skill           # refresh it
```

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".

<Warning>
  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.
</Warning>

`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:

```sh theme={null}
substrate validate
substrate diagnose
```

<Steps>
  <Step title="Run substrate validate">
    Loads every board and reports any files that fail the current schema. Fix or remove flagged files before continuing.
  </Step>

  <Step title="Run substrate diagnose">
    Confirms the environment, database, server, and skill are all consistent with the new binary version.
  </Step>
</Steps>

<Note>
  Substrate is pre-1.0. Board and schema shapes can still change between versions. The [CHANGELOG](https://github.com/42pe/substrate/blob/main/CHANGELOG.md) is where those changes are recorded — review it before upgrading in a team environment.
</Note>