Repository navigation
Updates and Hotfixes
How a fix reaches you without downloading the whole editor again — and what guarantees you never end up worse than you were.
Every release is a real version (0.5.0 → 0.5.1 → 0.6.0). What changes is
how it reaches each person:
| You are on… | You receive |
|---|---|
| the exact previous version, portable build | a small zip with only the files that changed |
| any other version, or the installed build | the full release |
| any case where the small zip fails | the full release, on its own, without fuss |
The result is identical in all three: the same files, the same version.
The pipeline picks the label by looking at the changes; the editor shows it, for example Latest Version: Minor update 0.5.0.
| Label | When | Number |
|---|---|---|
| Hotfix | only fixes, performance and maintenance | the last digit goes up |
| Minor update | fixes plus something new | the middle digit goes up |
| Release | does not fit in a small zip: the engine, dependencies, pi or the product identity changed | decided by the owner |
The label does not decide the download: a Minor update can arrive as a small zip, and a Hotfix can arrive whole if it has to.
Only an allow-list: the editor's code and screens (out/), the built-in
extensions including the PiCode connector, icons and media, and the setup
window. Electron, dependencies, pi, Engram and the product identity never
travel this way — they always mean a full release. A change that migrates
your data (chats, settings, memory) never travels in a hotfix either.
New versions of the pinned Gentle AI packages (gentle-pi, gentle-engram,
pi-intercom) do fit in a small zip; a new Engram program does not. How
those versions are picked up and when they reach you:
How Gentle AI stays up to date.
| What could go wrong | What covers it |
|---|---|
| the zip is for another version | the editor checks the version and, file by file, that the original is the expected one; otherwise it downloads the full release |
| someone tampers with the zip or the server | the manifest is signed; without a valid signature the zip is not applied |
| a path that escapes the folder | the whole package is rejected before anything is touched |
| a corrupt or cut-off download | a SHA-256 check of the zip and of each file, before and after copying |
| the update is applied halfway | it is applied to a copy of the installation, never the running one; on any failure the copy is thrown away |
| Windows will not replace open files | the swap happens with the app closed, by a script that waits for it to exit |
| the new version does not start | the previous one is only removed once the new one proves it started; if it does not within about 3 minutes, the previous version comes back with your profile |
| your portable profile |
data/ is never in the zip and is always kept |
The proof of start is a start check, not a check that every screen works.
- Only the portable build receives the small zip; the installed build updates with its installer.
- Only from the previous version: each channel keeps a single release (the newest), so someone two versions behind receives the full release.
- A fix for someone already on the latest version still needs a new version number: every hotfix is a version of its own.
Details and the exact rules live in the repository's
docs/HOTFIX.md
and ADR-034; the feed itself is described in
Distribution and Licensing.
Related: CI and Releases · Troubleshooting