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.
Rust acpagent-client-protocolai-agentsai-assistantclaudeclaude-codecodexcoding-agentscursorgeminigemini-cligrok-bot-alternativeiosiphonelinuxmacosmcpopen-sourcerustself-hosted
docs: document how app and host versions stay compatible
leepokaidcf720520286
diff --git a/AGENTS.md b/AGENTS.mdindex 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 Conventionsdiff --git a/CLAUDE.md b/CLAUDE.mdindex 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".## Targetsdiff --git a/docs/README.md b/docs/README.mdindex 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) |## Featuresdiff --git a/docs/guides/updates.md b/docs/guides/updates.mdindex 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).+## macOSRelease builds use Sparkle 2.10.0. Open **Settings → Updates** in the menu bardiff --git a/docs/reference/compatibility.md b/docs/reference/compatibility.mdnew file mode 100644index 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.