How sync works

Every Zeon project lives in the cloud. When you "open a project" in the Web IDE, you're browsing the cloud version directly. When you zeon clone it to your laptop, you get a local working copy you can edit.

This is cloud-canonical: the cloud is the source of truth. Your local working tree is a checkout that you sync back to the cloud with explicit commits.

Mental model

If you've used git before, Zeon's sync model will feel familiar:

• A commit is a snapshot of the entire project at a moment in time.
• A push sends new commits from your machine (or the IDE) to the cloud.
• A pull fetches new commits from the cloud to your machine.
• Every commit has a permanent id; you can look at any past commit, or roll back to one.

If you haven't used git, here's the short version: when you save your work, you create a snapshot. The cloud keeps every snapshot you've ever made, in order, so you can always go back.

Three places, one source of truth

A project can exist in three places:

1. The cloud, the source of truth.
2. The Web IDE, which talks to the cloud directly. When you click Commit & Push, the IDE writes a new commit to the cloud immediately.
3. A local working tree, created by zeon clone. You edit files locally, then zeon push your commits to the cloud.

The cloud doesn't care which one made the commit. The IDE and the CLI write into the same place.

What "syncing" actually does

Three operations move data between your local tree and the cloud:

In the Web IDE, commit and push are fused, so clicking Commit & Push does both in one go. There's no separate "save locally" step in the IDE.

In the CLI, commit and push are separate: you can zeon commit several times locally and zeon push them all at once.

What can go wrong: divergence

If two people (or two machines) commit at roughly the same time, the cloud accepts the first push and rejects the second. The rejected push gets a "Diverged from cloud" signal: there are commits in the cloud that aren't in your local copy.

When that happens:

• In the IDE: you'll see a red banner offering Reload from cloud (discards your local changes after confirming) or guidance to use the CLI for a merge.
• In the CLI: zeon pull either fast-forwards (if you have nothing local) or writes merge markers into the affected files for you to resolve, then commit + push.

See Resolving "Diverged from cloud" for the full flow.

Branches

For v1, every project has one branch: main. The platform stores the data needed for branches internally, but there's no UI or CLI surface to create or switch branches yet. The branch pill in the IDE always shows main.

When branch support lands, projects already in the system will work without changes, since your main is the only ref today.

History

Every commit is permanent and addressable by its id. You can:

• See the history with zeon log (or, soon, the IDE's history view).
• Look at the state of the project at a past commit with zeon checkout <commit-id>.
• Roll back the current main to an old commit with zeon reset <commit-id>.

The IDE's history view is currently a stub, so use the CLI for past-state inspection.

Single-user-per-project, for now

Zeon v1 assumes one operator per project at a time. You can absolutely sync the same project across multiple machines (your laptop, your robot's machine), but two people simultaneously editing the same workflow will produce divergence and you'll have to merge.

Multi-user collaborative editing (think Google Docs for workflows) is planned, not shipped.

Where to go next