Skip to content

Open source Grok Bot alternative, Bring your own agent and subscription: message Claude Code, Codex, Gemini CLI, Cursor, Copilot and 40+ AI agents as bots on your own computer, from iPhone, Mac, Windows, Linux or terminal. Agent-agnostic and free. Also a Muse and Dots alternative. Built in Rust.

docs: document how app and host versions stay compatible

leepokaidcf720520286
diff --git a/AGENTS.md b/AGENTS.md
index 3781c75b..030bf72f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -28,8 +28,9 @@ Always stop the old Mac app, host and iPhone process before running a new build
## Versioning & releases
- **Every source change ships as a release.** A version bump on `main` is the only release trigger (Auto Tag → DMG, host, Linux app, Homebrew, in-app update), so any change to shipped code (`apps/`, `kit/`, `host/`, `packaging/`) bumps the version before it reaches `main`, without being asked. Docs, `web/`, `cloud/`, `relay/` and CI-only changes don't bump.
+- Phone ↔ host compatibility: each side names the oldest version of the other it works with (`minApp` in the host's `hello`, `minHost` in each client). Additive changes need nothing; renames/removals raise `minApp` in two releases, after the iPhone version is live: [docs/reference/compatibility.md](docs/reference/compatibility.md)
- Pick the bump yourself: patch for fixes and small tweaks, minor for new features or protocol additions. Never bump major (stay on 2.x). One bump per merge into `main`: if `MARKETING_VERSION` is already ahead of the latest `v*` tag, leave it.
-- How: set `MARKETING_VERSION` in `apps/project.yml` and `version` in `host/Cargo.toml` (+ its `Cargo.lock` entry) to the same value, run `xcodegen generate --spec apps/project.yml`, commit as `build: bump version to X.Y.Z`. Never touch `CURRENT_PROJECT_VERSION` (Xcode Cloud sets the iOS build number). When the iOS app changes, also write that version's section in `apps/ios/WhatsNew.md` (zh-Hant + en-US, what iPhone users notice); it becomes the App Store "What's New".
+- How: set `MARKETING_VERSION` in `apps/project.yml` and `version` in `host/Cargo.toml` and `apps/linux/Cargo.toml` (+ their `Cargo.lock` entries) to the same value, run `xcodegen generate --spec apps/project.yml`, commit as `build: bump version to X.Y.Z`. Never touch `CURRENT_PROJECT_VERSION` (Xcode Cloud sets the iOS build number). When the iOS app changes, also write that version's section in `apps/ios/WhatsNew.md` (zh-Hant + en-US, what iPhone users notice); it becomes the App Store "What's New".
## Coding Style & Naming Conventions
diff --git a/CLAUDE.md b/CLAUDE.md
index 68a65dbb..8bed55c8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -62,11 +62,10 @@ Always stop the old Mac app, host and iPhone process before running a new build
## Versioning
-- **Major version** defines phone ↔ host compatibility: an iOS app works with hosts/Mac apps of the same major
-- Minor/patch bumps are always backward compatible within the same major; the iOS decoder is lenient (`Bot.init(from:)`) so small host additions don't break older apps
+- Phone ↔ host compatibility: each side names the oldest version of the other it works with (`minApp` in the host's `hello`, `minHost` in each client). Additive changes need nothing; renames/removals raise `minApp` in two releases, after the iPhone version is live: [docs/reference/compatibility.md](docs/reference/compatibility.md)
- **Every source change ships as a release.** A version bump on `main` is the only release trigger (Auto Tag → DMG, host, Linux app, Homebrew, in-app update), so any change to shipped code (`apps/`, `kit/`, `host/`, `packaging/`) bumps the version before it reaches `main`, without being asked. Docs, `web/`, `cloud/`, `relay/` and CI-only changes don't bump.
- Pick the bump yourself: patch for fixes and small tweaks, minor for new features or protocol additions. Never bump major (stay on 2.x). One bump per merge into `main`: if `MARKETING_VERSION` is already ahead of the latest `v*` tag, leave it.
-- How: set `MARKETING_VERSION` in `apps/project.yml` and `version` in `host/Cargo.toml` (+ its `Cargo.lock` entry) to the same value, run `xcodegen generate --spec apps/project.yml`, commit as `build: bump version to X.Y.Z`. Never touch `CURRENT_PROJECT_VERSION` (Xcode Cloud sets the iOS build number). When the iOS app changes, also write that version's section in `apps/ios/WhatsNew.md` (zh-Hant + en-US, what iPhone users notice); it becomes the App Store "What's New".
+- How: set `MARKETING_VERSION` in `apps/project.yml` and `version` in `host/Cargo.toml` and `apps/linux/Cargo.toml` (+ their `Cargo.lock` entries) to the same value, run `xcodegen generate --spec apps/project.yml`, commit as `build: bump version to X.Y.Z`. Never touch `CURRENT_PROJECT_VERSION` (Xcode Cloud sets the iOS build number). When the iOS app changes, also write that version's section in `apps/ios/WhatsNew.md` (zh-Hant + en-US, what iPhone users notice); it becomes the App Store "What's New".
## Targets
diff --git a/docs/README.md b/docs/README.md
index 6e500c73..05aa22a7 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -15,6 +15,7 @@ Source review, a passing build, local integration tests and production acceptanc
| Run the host on a Linux server or cloud VM | [Linux servers](guides/linux-servers.md) |
| Set up accounts, approvals or desktop SSH | [Accounts and SSH](guides/accounts-and-ssh.md) |
| Change transport or cryptography | [Remote protocol](reference/remote-relay.md) and [shared vectors](reference/fixtures/README.md) |
+| Change what the host and clients exchange | [Client and host compatibility](reference/compatibility.md) |
| Change an Apple screen or button | [UI conventions](design/ui-conventions.md) |
## Features
diff --git a/docs/guides/updates.md b/docs/guides/updates.md
index d0a5cda2..51a37fa6 100644
--- a/docs/guides/updates.md
+++ b/docs/guides/updates.md
@@ -1,5 +1,8 @@
# App and host updates
+A client and a host on versions that can't work together say which one to update:
+[Client and host compatibility](../reference/compatibility.md).
+
## macOS
Release builds use Sparkle 2.10.0. Open **Settings → Updates** in the menu bar
diff --git a/docs/reference/compatibility.md b/docs/reference/compatibility.md
new file mode 100644
index 00000000..33223e08
--- /dev/null
+++ b/docs/reference/compatibility.md
@@ -0,0 +1,91 @@
+# Client and host compatibility
+
+Clients (iPhone, Mac window, Linux app, terminal client) and the host update on different
+schedules: the iPhone app waits for App Review, Mac and standalone hosts update when their
+owner (or the opt-in automatic updater) installs a release, and the Linux desktop app is
+package-managed. Any client can meet an older or a newer host.
+
+## Rule
+
+Each side names the **oldest version of the other side** it still works with. Versions are
+the ordinary release versions (`MARKETING_VERSION`, `host/Cargo.toml`, `apps/linux/Cargo.toml`,
+always equal). There is no separate protocol number.
+
+| Floor | Lives in | Meaning |
+|---|---|---|
+| `minApp` | `host/src/compat.rs` `MIN_APP`, sent in `hello` | The oldest client this host serves correctly. |
+| `minHost` | `kit/.../Models/Compatibility.swift` `VersionMismatch.minHost`, `apps/linux/src/compat.rs` `MIN_HOST`, `host/src/compat.rs` `MIN_HOST` (terminal client) | The oldest host this client works with. |
+
+On every (re)connect the client reads `hello` and decides, in this order:
+
+1. its own version is below `minApp` → **Update this app**;
+2. the host's `version` is below its `minHost` → **Update Codync on <computer>**;
+3. otherwise it syncs normally.
+
+Versions compare as `major.minor.patch` (a leading `v` and any `-pre`/`+build` suffix are
+ignored). An unreadable version, or a `hello` without one, never blocks: an unknown is not a
+reason to lock someone out. Hosts from before 2.4.0 send no `minApp`; only the client's
+floor applies to them.
+
+## What each client does
+
+| | Apple apps (`BotStore.mismatch`) | Linux app | Terminal client |
+|---|---|---|---|
+| Notice | `UpdateNeededCard` above the computer's bots and in place of the composer; status reads *Needs update* | Banner over the roster | *needs update* in the status line, with the reason |
+| Update this app | iPhone: App Store page. Mac: Sparkle | Opens the GitHub release page (the desktop app is package-managed) | Text only |
+| Update the host | Mac: its own host is reinstalled from the app bundle. iPhone: instructions for that computer | `installHostUpdate` | `^k` → Check for updates |
+| Sync while mismatched | Stopped; `hello` is asked again every 30 s and on every reconnect | Continues (JSON is read leniently); sending is blocked | Continues; sending is blocked |
+
+Drafts are kept while sending is blocked. A host update restarts the host, so the reconnect
+reads the new `hello` and the notice goes away on its own.
+
+Apple apps also treat **undecodable data from a newer host** as *Update this app*: an event
+that stays undecodable after the one rewind, or a `hello` whose other fields can't be decoded
+(its `version` and `minApp` are still read). From an older or equal host it's only logged.
+
+## Changing what crosses the wire
+
+- **Additive changes need no floor change**: new fields (clients decode leniently; new
+ Swift fields are optional), new methods, new enum values (kept as strings).
+- **Renaming, removing or changing the meaning** of anything an older client reads or sends
+ needs `minApp` raised, in two releases:
+ 1. The host sends/accepts **both** the old and the new form; clients switch to the new one.
+ The iPhone part of this release must actually ship (it changes `kit/`, so `Submit iOS`
+ includes it).
+ 2. After that iPhone version is **live on the App Store**, a later host release drops the
+ old form and sets `MIN_APP` to the version from step 1.
+
+ Raising `MIN_APP` before the App Store has that version locks every iPhone out with no
+ update to install.
+- **Raise `minHost`** only when the client's core flows need something older hosts lack. An
+ optional feature that needs a newer host hides its control instead.
+- Floors never exceed the release that ships them (unit tests in both crates check this).
+- The encrypted channel's handshake version (`v` in its `hello`, rejected with
+ `unsupportedVersion`, close code 4400) is separate: the host must keep accepting every `v`
+ a supported client sends.
+
+## Floor history
+
+Update this table in the release that changes a floor, with the reason.
+
+| Release | Host `minApp` | Client `minHost` | Why |
+|---|---|---|---|
+| 2.4.0 | 2.3.0 | 2.3.0 | First release with the check. Since 2.3.0 the wire only gained `minApp` and lost the unused `protocol`; 2.3.0 is the oldest pairing verified to work, and a higher floor would lock out hosts that never auto-update. |
+
+## Trying it on a simulator
+
+Run a throwaway Debug host (it registers with the dev cloud) on its own data and port, never
+on `~/.codync` or 19222:
+
+1. Build a copy with a patched floor or version into a separate target, then restore the
+ source: e.g. `MIN_APP = "9.0.0"` in `host/src/compat.rs` (app too old) or `"version": "2.2.0"`
+ in `hello` in `host/src/api/mod.rs` (host too old), built with
+ `CARGO_TARGET_DIR=<scratch>/hosttarget cargo build`.
+2. `CODYNC_HOME=<scratch>/home <scratch>/hosttarget/debug/codync-host serve --port 19333`.
+3. Pair the simulator: `POST /api/pairing` with `<scratch>/home/token`, then launch with
+ `SIMCTL_CHILD_CODYNC_PAIR_URL=<pairingUrl>`.
+4. Swap hosts on the same `CODYNC_HOME` (patched ↔ normal) to see the notice appear in the
+ list and in place of an open chat's composer, and go away after the reconnect.
+
+The simulator has no App Store app, so *Update Codync* ends in a Safari error there; on a
+device it opens the App Store.