Settings reference
The complete list of per-repository settings. For how these combine, see Configuration overview; for the file you commit, see the.zar.yml reference.
Where: .zar.yml = settable in the repo file · dashboard = settable in the dashboard/database. The precedence rule is: dashboard (if set) → .zar.yml (if set) → default.
Documentation behavior
These shape how docs are produced and can live in.zar.yml.
| Setting | Type | Default | Values / range | Where | What it does |
|---|---|---|---|---|---|
trigger_mode (.zar.yml: trigger) | string | on_significant_change | every_commit, on_significant_change, daily, on_merge | .zar.yml + dashboard | When ZAR opens a docs PR. See Trigger modes. |
batch_hours | int | 24 | 1–168 (clamped) | .zar.yml + dashboard | Hours to batch pending changes before a PR. |
min_confidence (.zar.yml: threshold) | float | 0.6 | 0.0–1.0 (clamped) | .zar.yml + dashboard | Confidence required to act on a change. |
target_branch | string | main | any branch | .zar.yml + dashboard | The branch ZAR analyzes. |
pr_size | string | small | small, full | .zar.yml + dashboard | small ≈ 1–3 files; full = all changed docs. |
style_guide | string | empty | free text | .zar.yml + dashboard | Writing style passed to Claude. See Style guide. |
notify_slack | string / false | disabled | Slack webhook URL | .zar.yml only | Optional Slack notification (operator-dependent). |
min_confidenceis currently exposed via.zar.yml(threshold) and the API/database; it may not have a dedicated dashboard field in every build. Set it via.zar.ymlfor portability.
Write-back & gating
Operational switches — dashboard-only so a PR can’t flip them.| Setting | Type | Default | Where | What it does |
|---|---|---|---|---|
auto_commit_enabled | bool | false | dashboard | Allow direct commits. Also requires the DOCAGENT_WRITE_COMMITS env var. See Auto-commit. |
ci_gate_enabled | bool | false | dashboard | Block merges when docs look stale. See CI gate. |
required_doc_freshness | float | high (≈0.9) | dashboard | CI gate threshold. If ZAR proposes any doc change, freshness falls below this and the gate blocks. |
dry_run | bool | false | dashboard | Report only — never commit, never block. |
use_updates_branch | bool | true | dashboard | Commit to a dedicated zar-updates/… branch (vs. the PR head). |
disable_pr | bool | false | dashboard | Hard off switch — no docs PRs, no commits. |
comment_enabled | bool | true | dashboard | Post the status comment on PRs. |
debug_mode | bool | false | dashboard | Verbose logs + an extra “Debug Info” comment. |
Cross-repo docs
Dashboard-only. See Cross-repo docs. Team / Enterprise only.| Setting | Type | Default | What it does |
|---|---|---|---|
cross_repo_enabled | bool | false | Open docs PRs in a separate repository. |
docs_repo | string | — | Target docs repo, owner/repo (validated). |
docs_repo_path | string | /docs | Folder in the docs repo to write to. |
docs_repo_branch | string | main | Branch in the docs repo to target. |
Validation & clamping
batch_hours→ clamped to1–168; non-integer values are ignored (default kept).min_confidence/thresholdandrequired_doc_freshness→ clamped to0.0–1.0.trigger_mode→ invalid values fall back toon_significant_change.pr_size→ invalid values fall back tosmall.target_branch,docs_repo_path,docs_repo_branch→ empty values reset to their defaults (main,/docs,main).docs_repo→ must matchowner/repo, otherwise rejected.
Related
- Configuration overview — precedence and recommended setup.
.zar.ymlreference — the version-controlled file.- Environment variables — operator-level configuration (self-hosting).