cartulary 0.3.0-alpha.1

---
title: "`cartulary.toml` configuration reference"
summary: Wire schema of `cartulary.toml` — every accepted key, its type and default.
---

Every key accepted in `cartulary.toml`, walked from the serde Raw mirror in `src/infra/driven/fs/config/raw.rs`. Unknown keys are rejected at load time; optional fields use the type default unless noted.

Domain-level fallbacks (e.g. `[decisions.<kind>] dir` resolves to `docs/<kind>`, an unknown `preset` value falls back to the built-in default) live in `from_raw.rs` and are not visible from the wire schema alone — see the workflow pages and the project's init template for the effective defaults.

## Tables

- [Top-level keys](#top-level-keys)
- [`[query]`](#query)
- [`[site]`](#site)
- [`[[site.nav]]`](#sitenav)
- [`[issues]`](#issues)
- [`[issues.statuses.<name>]`](#issuesstatusesname)
- [`[tags.<name>]`](#tagsname)
- [`[decisions]`](#decisions)
- [`[decisions.<kind>]`](#decisionskind)
- [`[docs.<name>]`](#docsname)
- [`[sources.<name>]`](#sourcesname)

## Top-level keys

Strictness: rejects unknown keys.

| Key | Type | Optional | Default | Notes |
|---|---|---|---|---|
| `version` | integer (optional) | yes | type default | — |
| `issues` | [`[issues]`](#issues) (optional) | yes | type default | — |
| `decisions` | [`[decisions]`](#decisions) (optional) | yes | type default | — |
| `sources` | table of [`[sources.<name>]`](#sourcesname) entries (keyed by name) | yes | type default | — |
| `docs` | table of [`[docs.<name>]`](#docsname) entries (keyed by name) | yes | type default | — |
| `site` | [`[site]`](#site) (optional) | yes | type default | — |
| `query` | [`[query]`](#query) (optional) | yes | type default | — |
| `tags` | table of [`[tags.<name>]`](#tagsname) entries (keyed by name) | yes | type default | Tag descriptors at the config root. Each entry's `applies_to` declares which record kinds it scopes (`"issues"`, `"adr"`, …). |

## `[query]`

Strictness: rejects unknown keys.

| Key | Type | Optional | Default | Notes |
|---|---|---|---|---|
| `dir` | string (optional) | yes | type default | — |

## `[site]`

Strictness: rejects unknown keys.

| Key | Type | Optional | Default | Notes |
|---|---|---|---|---|
| `title` | string (optional) | yes | type default | — |
| `theme` | string (optional) | yes | type default | — |
| `out` | string (optional) | yes | type default | — |
| `nav` | array of [`[[site.nav]]`](#sitenav) | yes | type default | — |

## `[[site.nav]]`

Strictness: rejects unknown keys.

| Key | Type | Optional | Default | Notes |
|---|---|---|---|---|
| `label` | string | no | — | — |
| `url` | string | no | — | — |

## `[issues]`

Strictness: rejects unknown keys.

| Key | Type | Optional | Default | Notes |
|---|---|---|---|---|
| `dir` | string | yes | `default_issues_dir()` | — |
| `union` | array of strings | yes | type default | Additional read-only directories merged in for reads. See ISSUE-01F8K0WCA2BNB. |
| `id_prefix` | string (optional) | yes | type default | — |
| `preset` | string (optional) | yes | type default | — |
| `initial` | string (optional) | yes | type default | — |
| `statuses` | table of [`[issues.statuses.<name>]`](#issuesstatusesname) entries (keyed by name) | yes | type default | — |

## `[issues.statuses.<name>]`

Strictness: rejects unknown keys.

| Key | Type | Optional | Default | Notes |
|---|---|---|---|---|
| `next` | array of strings | yes | type default | — |
| `active` | boolean | yes | type default | — |
| `terminal` | boolean | yes | type default | — |
| `label` | string (optional) | yes | type default | — |
| `category` | string | yes | `default_status_category()` | — |

## `[tags.<name>]`

Strictness: rejects unknown keys.

| Key | Type | Optional | Default | Notes |
|---|---|---|---|---|
| `levels` | array of strings | yes | type default | — |
| `cardinality` | string | yes | `default_cardinality()` | — |
| `ordered` | boolean | yes | type default | — |
| `weights` | array of integers (optional) | yes | type default | — |
| `aggregate` | string (optional) | yes | type default | Rollup aggregation: `or`, `and`, `max`, `min`, or absent for no rollup. `max`/`min` require `ordered = true`. |
| `applies_to` | array of strings | yes | type default | Record kinds this descriptor scopes to. Empty = inert. |

## `[decisions]`

Strictness: tolerates unknown keys (dynamic-key table).

| Key | Type | Optional | Default | Notes |
|---|---|---|---|---|
| `types` | array of strings | yes | type default | — |
| _flattened_ | see [`[decisions.<kind>]`](#decisionskind) | — | — | dynamic sub-tables |

## `[decisions.<kind>]`

Strictness: rejects unknown keys.

| Key | Type | Optional | Default | Notes |
|---|---|---|---|---|
| `dir` | string (optional) | yes | type default | — |
| `union` | array of strings | yes | type default | Additional read-only directories merged in for reads. See ISSUE-01F8K0WCA2BNB. |
| `id_prefix` | string (optional) | yes | type default | — |
| `statuses` | any (optional) | yes | type default | Accepted-and-ignored: the DR workflow is hardcoded. `cartu migrate v5→v6` strips this key, but older configs may still carry it. |
| `preset` | string (optional) | yes | type default | Accepted-and-ignored, same rationale as `statuses`. |

## `[docs.<name>]`

Strictness: rejects unknown keys.

| Key | Type | Optional | Default | Notes |
|---|---|---|---|---|
| `type` | string | no | — | — |
| `source` | string | no | — | — |
| `publish` | string | no | — | — |

## `[sources.<name>]`

Strictness: rejects unknown keys.

| Key | Type | Optional | Default | Notes |
|---|---|---|---|---|
| `type` | string | no | — | — |
| `url` | string | no | — | — |
| `project` | string | no | — | — |
| `token_env` | string | no | — | — |
| `status_map` | table of string entries (keyed by name) | yes | type default | — |