# Config versions

> Immutable snapshots of every rule, skill, coin payout, and item. Buddies pin to a snapshot so their world never shifts unexpectedly.

Source: https://docs.hatched.live/docs/concepts/config-versions

Drafts are your working copy. Publishing freezes them. Each buddy carries a
`config_version_id` that the [rule engine](/docs/concepts/rule-engine) loads
on every event. Migration is explicit — you decide when a buddy moves to a
newer version.

## Why versions exist

Without versioning, tweaking a coin payout silently changes every live
buddy's behaviour. With it, you can always explain exactly why a buddy did
what it did.

## Example

> Bump `lesson_completed` from +10 → +25 coins in the draft. Publish. New
> eggs hatch pinned to v12. Existing buddies stay on v11 until you migrate
> them.

## How to work with drafts

1. Make changes freely — they land on the draft.
2. Review the diff under Publish before flipping it live.
3. Migrate buddies in bulk or individually when you're ready.

## Lifecycle

- **Draft** — your working copy, mutable.
- **Published** — immutable; new buddies pin to it.
- **Archived** — old snapshot still valid for pinned buddies, no longer
  available for new pins.

## Gotchas

- Migration swaps the **rulebook**, never the state. Coins, badges, streak
  counters all carry over when a buddy moves to a new version.
- Archiving a version doesn't migrate its buddies; they keep running under
  the old snapshot until you explicitly move them.
- Preset changes from Hatched itself land as a new version for your
  customer — they never silently modify your draft.

## Related

- [Rule engine](/docs/concepts/rule-engine) — loads the pinned version on every event.
- [Audiences](/docs/concepts/audiences) — per-audience rule overrides live in the version.
- [Configure rules](/docs/guides/configure-rules) — editing drafts and publishing.