Resolving a diverged project

"Diverged from cloud" means there are commits in the cloud that aren't in your local copy and you have local changes that aren't in the cloud. Both sides have moved forward and they need to be reconciled.

This happens when:

You and someone else (or another machine you own) committed at roughly the same time.
You started editing in the IDE on one device, then started editing in the CLI on another.
You let the IDE sit open for a while and someone pushed in the meantime.

The fix depends on whether you're in the IDE or the CLI.

In the Web IDE

When the IDE detects divergence on a commit attempt, you'll see a red banner between the toolbar and the editor:

Diverged from cloud. Someone else has pushed commits to this project. [Reload from cloud]

Click Reload from cloud. The IDE asks you to confirm (because it'll discard your local edits), then fetches the latest cloud state and drops your in-progress changes.

That's the only option in the IDE today. If you want to keep your local edits and the cloud's edits, switch to the CLI for the merge.

⚠️
Before you click Reload from cloud: if you can't afford to lose your local changes, copy the affected files out of the IDE first (open each one and copy-paste the contents into a notepad). Then reload, then paste them back, edit, commit. It's a workaround, not a feature. A real per-file revert and 3-pane merge view are on the roadmap.

In the CLI

⭐
Most of the time, zeon sync handles this for you. It pulls, merges, and pushes in one step, so divergence resolves itself unless the same lines really did change in both places. Reach for it first: see zeon sync. The manual pull flow below is what sync does under the hood, and is still useful when you want to inspect the merge before pushing.

zeon pull is built for this case. It does one of three things:

Same commit. No-op.
Cloud is ahead, you haven't committed anything. Fast-forwards your local tree to match the cloud.
Both sides moved. Writes merge markers into the conflicting files for you to resolve.

The third case is the interesting one. After zeon pull, a conflicted file looks like:

<<<<<<< HEAD (local)
{
  "node_count": 4,
  "version": 12
=======
{
  "node_count": 5,
  "version": 11
>>>>>>> 3f8a... (remote)
}

The chunk between <<<<<<< and ======= is what you had locally. The chunk between ======= and >>>>>>> is what's in the cloud. Your job is to edit the file so it has the version you want (usually a combination of the two) and remove the marker lines.

After you've cleaned up every conflicted file:

zeon status                    # confirm no files still show "Unmerged"
zeon commit -m "Merge cloud changes with local edits"
zeon push

Avoiding divergence in the first place

A few habits reduce how often you hit this:

Use zeon sync as your default. Because it always pulls before it pushes, it prevents most divergence from ever becoming a problem.
Keep your IDE tab and your CLI working tree synced. If you've been editing in the IDE, run zeon sync on the CLI side before editing locally.
Commit and push often. Small, frequent commits are easier to merge than long-running uncommitted edits.
One person per project at a time. Coordinate with collaborators if you're sharing a project. Multi-user concurrent editing isn't supported yet.
On the robot machine, zeon sync before each run. That way the workflow you're about to run is the latest one.

What "Diverged from cloud" does not mean

A few things that look like divergence but aren't:

You just opened the project in a new tab. The IDE always shows the latest cloud state; opening a fresh tab can't be diverged.
You committed locally with the CLI but haven't pushed. That's ahead of the cloud, so push when you're ready, no merge needed.
You see commits in zeon log that you didn't make. That's history: someone else's past commits. Not a divergence.

True divergence is when both sides have new commits since they last agreed.