kronika sync
Reconcile every manifest-declared document with its repository evidence: establish baselines, audit drifted documents, rewrite only audited defects, and record the reconciled commit.
Invocation
kronika sync [options]
A schema-version 1 sync manifest is required at kronika.sync.json by default. Each document entry must have a non-empty output and non-empty sources array. BRAMA_URL and a BRAMA_API_KEY_ROLE credential reference are required even when the current tick needs no model call. Secrets are resolved through the configured credential source, not read directly from environment variables.
Inputs and options
| Option | Default | Effect |
|---|---|---|
--repo <path> | current directory | Git repository containing manifest, state, sources, and outputs. |
--manifest <path> | kronika.sync.json | Sync manifest inside the repository. |
--state <path> | kronika.sync-state.json | Persistent reconciliation baselines. |
--model <selector> | KRONIKA_MODEL or any | Default Brama model unless a document overrides it. |
--max-input-bytes <n> | none | Total source budget for documents that state none; unset, sources are read whole. |
--max-file-bytes <n> | none | Per-file source limit for documents that state none. |
--max-diff-bytes <n> | none | Complete-diff limit for documents that state none; unset, the whole diff is audited. |
--max-tokens <n> | none | Completion token budget for documents that state none. |
--dry-run | off | Reports and audits but writes no document or state, and never commits. |
--commit | off | Stages rewritten documents and state, then creates a sync commit when something changed. |
--push | off | Runs git push after a sync commit; requires --commit, otherwise the invocation is refused before credential resolution. |
--json | off | Emits the machine-readable tick result. |
Output and state
Text starts with Kronika sync at <sha12>, with (dry run) when applicable, then reports one outcome per document: baseline, current, advanced, checked-current, rewritten, or failed. JSON includes headSha, dryRun, committed, stateWritten, and complete outcomes with changed paths and findings.
A first non-dry run records a baseline and generates nothing. An unchanged baseline is current. If no declared evidence changed, the baseline advances without Brama. Changed evidence is audited; a passing audit advances state without prose churn, while blockers cause an atomic rewrite using those findings as the correction brief. State is written only when a baseline advances. Any failed outcome makes the process exit 1; otherwise it exits 0.
With --commit, sync commits rewritten outputs and state as kronika sync: reconcile <files>, or state alone as kronika sync: advance documentation baselines. --push pushes that commit.
Exact refusals and failed outcomes
sync --push requires --commit: usage refusal before any model or Git work.Sync manifest is missing: <path>. Declare the maintained documents first.Sync manifest is not valid JSON: <path>orUnsupported sync manifest schemaVersion in <path>Sync manifest declares no documents: <path>Sync manifest entry without an output path in <path>orSync manifest entry <output> declares no sourcesSync state is not valid JSON: <path>. Fix or delete it to re-baseline.orUnsupported sync state schemaVersion in <path>BRAMA_URL is required: the address of the Brama gatewayandBRAMA_API_KEY_ROLE is required: ROLE#FIELD naming the role the item holding the Brama bearer plays, and its field
A baseline that cannot be diffed yields a failed outcome instructing the operator to delete that state entry to re-baseline. An incomplete audit yields audit did not complete: <message>; a blocked audit whose rewrite fails yields audit found blockers but the rewrite did not complete: <message>. Git commit or push failures are process errors. See the sync loop for the complete state machine.