journal sync

Publish pending entries to the remote journal repo (and refresh local cache).

The single command that writes to your remote journal repository.

doraval journal sync

sync is the only command that modifies the GitHub repo. Everything else (add, list, update) is local or read-only.

What it does

Refreshes your local cache (~/.doraval/journals/) from the remote (global + current project). This is new behavior — sync always pulls first.
Reads any staged entries from ~/.doraval/pending/<project>/.
If there are none → refreshes the cache and exits cleanly with a message.
If there are pending entries:
- Fetches the latest remote version of the project file (with SHA for safe conditional write).
- Appends the new entries.
- Pushes the combined file back to GitHub using the Contents API.
- Clears the local pending directory.
- Re-fetches the final state into the local cache.

Flag	Description
`-p, --project`	Project to sync (defaults to current directory mapping)
`-m, --message`	Custom commit message

Uses GitHub’s conditional update (SHA) so concurrent writes from other machines are detected and rejected.
Never writes directly from add — staging + explicit sync prevents accidents.
Requires the gh CLI with appropriate permissions on the journal repo.

At the end of a focused session after using journal add.
Any time you want to share decisions with your future self or with agents on other machines.
sync is also a convenient “make sure my cache is fresh + publish if anything is waiting” command.

See journal update for a pure refresh without any publish attempt.

The full architecture (including why only sync writes) is explained in How the Agent Journal Works.