Conflicts

A conflict happens when two devices try to change the same page at the same time, or when a remote change lands while your local copy still has unsaved edits. MindWiki never silently picks a winner. Instead, it preserves both versions.

How conflicts are created

The sync model uses optimistic concurrency: when you push a change, you also tell the server what state you thought you were updating from. If the server's current state has moved on, your push is rejected — and the local client writes a conflict file so your work isn't lost.

A conflict file is a regular markdown file with a name like:

my-page.conflict-macbook-pro-1747100000000.md

The components: the original file's base name, then conflict-, then the device that created the conflict, then a timestamp. Both the original page and the conflict file end up in your vault, side by side.

When you see a conflict file

Open both files. The original holds the version that landed on the server. The conflict file holds the version your device tried to push. Common cases:

  • Two devices edited the same page. Both tried to push. The first one wins; the second creates a conflict file with the loser's content.
  • You edited locally while offline; a remote change landed first. When you reconnect, your push loses to the already-applied remote change. The conflict file holds your local edit.
  • A remote delete arrives while you have local edits. The delete applies, your local edit is preserved as a conflict file.

Resolving a conflict

There's no automatic merge. The right move is human:

  • Read both files. The original (now on disk) and the conflict file.
  • Decide what the page should actually say. Sometimes the conflict file's content is better. Sometimes the original is. Sometimes you want a merge.
  • Edit the original to the desired final state.
  • Delete the conflict file when you're done.

This takes a few minutes per conflict. It's intentional friction — we'd rather you spend that minute than have an automatic merge silently lose half your edits.

Avoiding conflicts

A few habits make conflicts rare:

  • Save before walking away. The macOS app auto-saves on every keystroke, but if you're switching to the web app, give sync a few seconds to settle.
  • Don't edit the same page on two devices simultaneously. This is the only reliable way to produce a conflict in normal use.
  • Watch the sync indicator. The macOS status bar shows last-synced time. If it's not recent, wait before making more edits.

Conflicts and AI clients

When an AI calls mindwiki_write_page, it sends the same base_hash concurrency token. If the page changed since the AI read it, the write returns a 409 conflict and the AI is told the current hash. Well-behaved clients re-read and retry; a misbehaving client could in theory create a conflict file, but in practice OAuth-connected AI clients handle this cleanly.

Where conflicts don't happen

  • Attachments in _assets/ are addressed by content hash. If two devices upload the same content, only one copy is stored — no conflict.
  • Page deletes with base_hash mismatch return 409 instead of producing a conflict file. The client retries or surfaces the inconsistency.

If conflicts pile up

If you find yourself with many conflict files (e.g. after extended offline use across two Macs), do them in order:

  • Sort the conflicts by timestamp.
  • Resolve oldest first — that gives you the cleanest merge surface for newer ones.
  • Save and let sync settle between resolutions.

A bulk conflict resolver is on the roadmap. For now, the file-by-file workflow is the supported path.

Where to go next