Configuration Reference

Pulls in a built-in preset as the base. Your config is deep-merged on top: - roles: appended (duplicates silently merged) - relations: merged at all levels - matrices: merged by name; a child replaces a same-named matrix - linkDisplayPolicies: merged by name; a child replaces a same-named policy in full

If extends is omitted, the config is standalone — no preset is loaded.

Presets can themselves extend another preset. In a preset file, extends is a top-level field next to name and version:

Inheritance chains resolve transitively; circular inheritance is rejected. See Presets Reference for the preset schema.

Flat list of strings. Every [item] must use a role in this list. Case-insensitive. Unknown roles generate warnings.

Nested map: source_role → target_role → type → { reverse }. Each relation type is a key with a mandatory reverse — the authorable name for the same edge seen from the other side.

Both names are authorable: a design may write addresses:REQ-001[], or a requirement may write addressed_by:DES-001[]. Either authoring stores the same canonical edge (design → requirement : addresses).

The reverse direction is allowed automatically — you do not declare requirement → design separately. Symmetric relations declare themselves as their own reverse:

If a relation type is used that is not declared (or derived as a reverse), the extension reports an error with the allowed alternatives.

linkDisplayPolicies is a map of named link display policies. Each policy must define a non-empty hide array containing one or more rules. A matching rule hides a relationship only from the view of its currentItem; it does not remove the graph relationship. All specified conditions in one rule must match; any matching rule hides the link. The relation type is interpreted from the displayed item’s perspective using the configured reverse relation, so authored direction does not change matching. Each rule’s relation type must be declared in relations. Each endpoint matcher must specify role, attributes, or both.

The complete policy and matrix-selection example appears in the traceability.yml sample above.

Preset inheritance merges policies by name; a child policy replaces the full parent policy with the same name. The selector value none disables filtering and is reserved as a policy name, case-insensitively. Unknown document policy names report the source file; unknown matrix policy names report the matrix and policy.

A baselined item is superseded rather than edited in place. The successor declares supersedes (reverse superseded_by) to the item it replaces.

An item is superseded when one or more incoming supersedes relationships target it — no status attribute is required. Splits (one predecessor, several successors) and merges (one successor, several predecessors) are supported. Self-supersession, duplicate links, and cycles are validation errors.

Current-state matrices omit superseded items. Functional links to a superseded item remain visible and are marked for review. See supersession check for the read-only impact report.

Optional display-only map: type → human-readable name. Never affects graph structure, merge behavior, or validation.

If a type has no labels entry, the humanized type name is used: underscores become spaces, sentence-cased (is_derived_from → "Is derived from").

An array of matrix definitions:

The filter expression uses an allowlisted grammar and is never evaluated as code. Omitting rowFilter keeps all current items of the configured row role.

Per-role authoring guidance for AI agents and humans. Each entry maps a role to an AsciiDoc page describing how to write items of that role, plus an optional ID prefix fallback:

Built-in presets ship default guidance pages. A project’s roleGuidance overrides the preset per role. Resolve guidance from the CLI with antora-tracer role-guidance <role>.

Opt-in remote ID allocation for the next-id command. When set, next-id requests the next ID from a shared allocator instead of scanning local files:

endpoint must be a non-empty HTTP(S) URL. token, when set, is sent as Authorization: Bearer <token>.

Both values support environment-variable interpolation. Keep secrets out of the committed file. An unset endpoint variable fails configuration loading. An unset token variable does not prevent configuration loading or site generation. Remote next-id reports the missing variable and fails before contacting the allocator. --local does not require the token. The CLI loads a .env file from the working directory at startup, so you can keep the token there instead of exporting it.

When endpoint is set, next-id fails closed: an unreachable allocator, a non-2xx response, or a malformed body exits with an error rather than falling back to a local ID. A 401 or 403 response is reported as an authentication failure. Pass --local to force the local scan regardless.

Absent idAllocation, next-id keeps its local max+1 behavior unchanged.

The allocator itself is the separate ID allocation server package.