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: deploy cloud changes to dev before main and to main after merge

leepokai15dbf75f24be
diff --git a/AGENTS.md b/AGENTS.md
index ebec7888..f4de85d3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -43,6 +43,7 @@ After every change, test it end to end on the real apps, not just builds and uni
## Versioning & releases
- **Every source change ships as a release.** A version bump on `main` is the only release trigger (Auto Tag → desktop app for macOS, Linux and Windows, host, Homebrew, in-app update), so any change to shipped code (`apps/`, `host/`, `packaging/`) bumps the version before it reaches `main`, without being asked. Docs, `web/`, `cloud/`, `relay/` and CI-only changes don't bump.
+- **`cloud/` is deployed by hand, never by CI.** A dev → main PR that changes `cloud/` first runs `npm run deploy:dev` and is tested end to end on dev; right after it merges, run `npm run deploy:main` (plus any new bucket/migration) and check the new routes, so dev never works while main fails: [releasing cloud changes](docs/guides/environments-and-deployment.md#releasing-cloud-changes).
- 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; a rename/removal raises `minApp` in the same release, and the release gate holds that release until the App Store has the iPhone app: [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. A change to `host/crates/memory` also raises `codync-mem`'s own 0.x version once per release (leave it if it's already ahead of `main`'s); CI blocks a PR into `main` that forgets, and the merge publishes it to crates.io ([codync-mem releases](docs/guides/development.md#codync-mem-releases)).
- How: set `MARKETING_VERSION` in `apps/project.yml` and `version` in `host/Cargo.toml` (+ its `Cargo.lock` entry) and `apps/desktop/package.json` (+ `package-lock.json`) 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 a phone app changes, also write that version's section in its notes (zh-Hant + en-US, what that app's users notice): `apps/ios/WhatsNew.md` becomes the App Store "What's New", `apps/android/WhatsNew.md` the Google Play release notes.
diff --git a/CLAUDE.md b/CLAUDE.md
index 6102a1f9..839f1da4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -72,6 +72,7 @@ After every change, test it end to end on the real apps, not just builds and uni
- Xcode Cloud archives the `iOS` scheme on every `v*` tag and uploads it to App Store Connect with its own build number, then the `Submit iOS` workflow submits it to App Review for the App Store; don't upload from the local machine or edit `CURRENT_PROJECT_VERSION` for it. Details: [development guide](docs/guides/development.md#ios-releases-xcode-cloud). `Submit Android` builds the same tags and uploads them to Google Play ([Android releases](docs/guides/development.md#android-releases-google-play)).
- 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; a rename/removal raises `minApp` in the same release, and the release gate holds that release until the App Store has the iPhone app: [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 → desktop app for macOS, Linux and Windows, host, Homebrew, in-app update), so any change to shipped code (`apps/`, `host/`, `packaging/`) bumps the version before it reaches `main`, without being asked. Docs, `web/`, `cloud/`, `relay/` and CI-only changes don't bump.
+- **`cloud/` is deployed by hand, never by CI.** A dev → main PR that changes `cloud/` first runs `npm run deploy:dev` and is tested end to end on dev; right after it merges, run `npm run deploy:main` (plus any new bucket/migration) and check the new routes, so dev never works while main fails: [releasing cloud changes](docs/guides/environments-and-deployment.md#releasing-cloud-changes).
- 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. A change to `host/crates/memory` or `host/crates/network` also raises that crate's own 0.x version (`codync-mem`, `codync-network`) once per release (leave it if it's already ahead of `main`'s); CI blocks a PR into `main` that forgets, and the merge mirrors and publishes it to crates.io ([crate releases](docs/guides/development.md#codync-mem-releases)).
- How: set `MARKETING_VERSION` in `apps/project.yml` and `version` in `host/Cargo.toml` (+ its `Cargo.lock` entry) and `apps/desktop/package.json` (+ `package-lock.json`) 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 a phone app changes, also write that version's section in its notes (zh-Hant + en-US, what that app's users notice): `apps/ios/WhatsNew.md` becomes the App Store "What's New", `apps/android/WhatsNew.md` the Google Play release notes.
diff --git a/docs/guides/environments-and-deployment.md b/docs/guides/environments-and-deployment.md
index f7c2c7ae..67d5a43c 100644
--- a/docs/guides/environments-and-deployment.md
+++ b/docs/guides/environments-and-deployment.md
@@ -59,6 +59,16 @@ Production also needs completed Apple native application registrations in Clerk
A migration that changes what the database accepts goes out before the Worker code that relies on it, in each environment: dev first, then main. `wrangler d1 migrations list <db> --remote` shows what an environment still lacks. Before applying one to main, note the restore point (`wrangler d1 time-travel info codync`) and compare the live schema with `cloud/migrations/`.
+## Releasing cloud changes
+
+CI only tests `cloud/`; nothing deploys it. A dev → main PR that changes `cloud/` (routes, bindings, migrations) goes out in this order:
+
+1. Before the PR merges: create any new binding in dev (R2 bucket, rate limit, D1 migration), `npm run deploy:dev`, and test the changed flows end to end against `dev-api.codync.dev` with the dev apps.
+2. Right after the merge into `main`, before or with the release tag: create the same bindings for main (`wrangler.toml` names them, e.g. `codync-icons` beside `codync-icons-dev`; keep R2 buckets private), apply migrations, `npm run deploy:main`.
+3. Check main: each new route on `api.codync.dev` answers (401 without credentials, not 404), and `npx wrangler deployments list` shows the new version.
+
+Clients and host that call a new route must not reach users before step 2. In 2026-10, custom icons shipped in v2.33.2 while production cloud was days old and its R2 bucket missing, so every upload failed.
+
## Secrets audit
The repository is public, so its whole history counts as published. Last scan: 2026-10-07 (`gitleaks git .` plus pattern grep over `git log -p --all`).