# ADR-001 — Git-first canonical playbook content

## Status

Accepted

## Context

Built-in playbooks need human review, semantic versioning, reproducible releases, package export and transparent diffs. Storing only opaque database rows would weaken these workflows.

## Decision

Canonical built-in content is stored as YAML/Markdown packages in Git. The application validates, canonicalizes and indexes immutable versions into PostgreSQL. Private authoring may use database drafts but exports the same package format.

## Consequences

Positive:

- ordinary Git review and history;
- portable packages;
- reproducible catalog builds;
- CI validation;
- no database lock-in for authored content.

Negative:

- import/index synchronization required;
- file and database lifecycle must be clearly separated;
- package migrations need tooling.