Updating a Package

Ship a new version

1. Make your changes.
2. Bump metadata.version in elizon.yaml, following semantic versioning:
   • patch (1.0.1) for fixes that change no behaviour an operator relies on,
   • minor (1.1.0) for additions,
   • major (2.0.0) when something an operator configured or relies on changes or goes away.
3. validate, build and sign as usual. Keep namespace and name the same: they're what makes it the same Package.
4. If the new version relies on newer platform features, raise compatibility.minPlatformVersion.

What operators see

An operator updates from the Package's page in Studio → Packages → Update, by uploading the new .pkg. Before anything changes, Elizon shows an object-level plan, e.g. "modifies 2 Agents, adds 1 Workflow, removes 1 Tool", compared against what was installed, not against the new version's own description of itself.

• Objects the operator edited after installing, which the new version also changes, are listed as conflicts. The operator chooses for each one: keep mine or take theirs. Nothing is overwritten without an answer.
• Objects the new version drops but something else still uses are kept as the operator's own resources, not deleted.
• A changed compliance block is shown separately and prominently, and the operator must acknowledge it. A Package quietly starting to process a new kind of data is the most serious change an update can make.

The update records a new installation, and the old one is marked superseded. Its objects carry on under the new record.

Designing for smooth updates

• Keep object names stable. Renaming an object in the manifest looks like a removal plus an addition.
• Keep Slot ids stable. Operators' bindings are keyed by Slot id.
• Don't change the embedding model's Slot casually. Changing the model invalidates Knowledge Base indexes.
• Say what changed. Operators read the plan; a clear description on new objects and Slots makes it readable.
• Treat compliance changes as releases in their own right. If you start processing personal or financial data, expect operators to ask why.