diff --git a/CLAUDE.md b/CLAUDE.md
index 1d312f5b7..72742c096 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -32,6 +32,16 @@ The `gh` command is available to interact with GitHub from the terminal, but **N
 - **Always use `git mv` instead of `mv`** when renaming or moving files - preserves git history tracking
 - **NEVER run `git stash`** - it causes work loss
 
+**Branch contents:**
+- `main` is the open-source build: local-first, BYO-keys, full AIX and provider coverage
+- `dev` extends `main` with the hosted/cloud layer: auth, Zync sync, Cloud Fabric, Stripe, multi-tenant, admin pages, it's the way to go for users, the best user experience of any multi-model chat application
+- Cloud/auth/sync code stays on `dev`; non-cloud improvements (UX, AIX, model support, bug fixes) can land on either branch
+
+**Branch workflow:**
+- `dev` is rebased on top of `main` (never merged) - `main` changes flow into `dev` on the next rebase, no manual forward-port needed
+- Never `git merge` between the two branches - breaks the linear topology
+- Backporting `dev` -> `main` is a re-implementation, never a cherry-pick - keep `main`-side edits minimal/additive so the existing `dev` version lands cleanly on rebase; split into small commits when natural
+
 ### Core Directory Structure
 
 You are started from the root of the repository (i.e. where the git folder is or scripts should be run from).