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

# Version Control & Upgrades

Charm versions are driven by the agent manifest and the published bundle.

## Agent Version

Update `persona.version` in `charm.yaml` when publishing a new agent version:

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
persona:
  version: "0.2.0"
```

Use semantic versioning where possible:

* patch: bug fixes,
* minor: new compatible features,
* major: breaking changes.

## Agentic Merge Upgrade Process

Charm uses an intelligent "Agentic Merge" approach for OTA updates to preserve your local workspace modifications while applying new bundle changes.

For detailed information on how this process works under the hood, including execution logic and fallback mechanisms, see the [Agentic Merge documentation](../platform/agentic-merge).

## Upgrade Safety

Before publishing:

* run validation,
* test locally,
* test Docker mode for runtime changes,
* document breaking changes,
* keep previous version available for rollback.

## Daemon Agents

Daemon agents may need restart or upgrade handling because they run persistently. Test daemon upgrades in preview before production.

## Best Practices

* Publish small changes.
* Avoid changing input schemas without migration notes.
* Keep changelog entries user-facing.
* Use Git tags for important releases.