Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

docs(versioning): separate the compatibility gate from the artifact version (CHOO-1865)

Louis Amaudruz9e323c23d2a1
diff --git a/docs/VERSIONING.md b/docs/VERSIONING.md
index 76e8630da..ffa6730c4 100644
--- a/docs/VERSIONING.md
+++ b/docs/VERSIONING.md
@@ -69,6 +69,16 @@ else operates, switchdash has no visibility at all.
**No client version reaches the server.** There is no version header, no field
on agent registration, and no version column on any client-bearing table.
+**Why the artifact version matters even though contracts decide compatibility.**
+The compatibility gate (§3) reads contract versions only — an artifact version
+never decides whether two components may talk. The artifact version is still
+required for everything around that decision: reporting that a newer release
+exists (§4), folding a release path to work out what a move costs (§5.1),
+refusing a switch-core downgrade whose database has already migrated forward
+(§8.1), naming the `untested` release combinations (§4.1), and answering "what
+are you running?" in a bug report. Both travel on the same endpoint, so this is
+one primitive rather than two.
+
### 1.3 "Unknown" currently renders as "fine" — in four places
The ticket's non-negotiable rule is that *incompatible*, *untested* and