Sync, offline work, and conflicts

Most of the time, synchronization should be boring. The background service watches your managed skills and keeps the versions you should have installed current.

Private sync uses the same system

There is no separate private-sync service to configure.

For your own skills, valid private revisions upload and synchronize across your signed-in devices automatically. You can keep a skill private indefinitely; public publishing is unrelated to whether Denju can keep your own copies current.

For teams, a normal team publish creates a team-only release. Team members with a direct subscription can receive that private release, and assigned packs can keep private team skills synchronized across the team automatically. Unfinished maintainer edits remain private until they are published as a team release.

Force a complete sync

denju sync

sync is a one-shot check of everything Denju currently knows about. It uploads pending edits, downloads updates, applies pack changes, repairs managed harness links, removes skills that are no longer needed, then exits.

If one skill is blocked by validation, an edit conflict, or two policies asking for different versions, Denju reports that skill instead of waiting forever. Unrelated skills can continue synchronizing.

Work offline

Owned skill edits are recorded locally first. If the registry is offline, valid private revisions remain queued and upload when connectivity returns.

Likewise, a storage-quota problem does not block local editing. denju usage shows the applicable storage limit, current usage, and queued local bytes. Eligible unreleased private history can be pruned explicitly:

denju history prune @alice/my-skill

Denju never silently deletes history just because it is old.

Invalid working content

If a managed skill becomes structurally invalid—for example, required frontmatter is missing—Denju does not overwrite your local work with a remote version. That skill enters a paused validation state. Fix the working tree and run denju sync again.

Changing the name field directly is treated as a pending rename because the skill name is package identity. Denju preserves your edit and tells you to run the explicit denju rename ... operation.

Concurrent edits on two devices

Suppose two devices start from the same private revision and both save.

Denju never resolves that race by silently taking the last writer. Both immutable heads are preserved. The client then performs a three-way merge from the common parent.

• Changes to different files merge automatically.
• Non-overlapping edits in the same text file can merge automatically.
• Overlapping edits create an explicit conflict for that skill.

Check the conflict:

denju status
denju diff @alice/my-skill <head-a> <head-b>

To keep one complete head, use the exact denju restore command printed by status. To create a custom resolution, edit the preserved working tree and run:

denju sync

The resolved result becomes a new two-parent revision, so neither original head disappears from history.

When two install policies disagree

A content conflict means two people or devices edited the same skill history.

A policy conflict means two equally strong rules ask Denju to install different exact versions of the same skill—for example, two teams assign packs that pin that skill differently.

Denju does not guess which team should win. It keeps the last valid version visible when possible, pauses only that skill, and shows both policies plus exact resolution commands in denju status.

Repair the installation itself

Use doctor when the problem is the Denju installation itself rather than one skill or policy:

denju doctor

It checks local database health, the background service, stored credentials, Codex/Claude skill locations, broken or duplicate Denju links, registry connectivity, and interrupted local work.