# Data Model: AI-Facing Repository Constitution

## Entities

### Constitution
- **Role**: Source of truth for AI about repository rules, architecture, conventions, precedence.
- **Key Fields**: scope (modules, hosts, secrets, proxies), conventions (no blank lines, comment discipline, factor duplication), precedence (constitution over human docs for AI), update triggers, references index, success criteria links.
- **Relationships**: Links to Use-case Playbooks and Reference Map; references repo paths.

### Use-case Playbook
- **Role**: Workflow guide for repeatable actions (add module/server/script/host/secrets).
- **Key Fields**: use-case name, required inputs, steps, expected outputs, related helpers (e.g., mkserver), secrets mapping, host/toggle implications.
- **Relationships**: References Constitution for rules and Reference Map for file locations.

### Reference Map
- **Role**: Index mapping core concerns to repo paths for navigation and validation.
- **Key Fields**: category (apps, dev, scripts, servers, services, shell, network, users, nix, patches), hosts list (emacs, server, workstation), secrets files, proxy rules, auto-import rules, stylix/schemes.
- **Relationships**: Anchors citations used by Constitution and Playbooks.

## Constraints and States
- **Lifecycle**: Constitution updates trigger playbook/index updates; playbooks evolve with new workflows; reference map updates when repo structure changes.
- **Validation Rules**: Constitution must enumerate all categories/hosts; secrets map must be complete; discoverability within two steps; precedence must be explicit.