Data Model: AI-Facing Repository Constitution

Entities

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.

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.

Role: Index mapping core concerns to repo paths for navigation and validation.
Key Fields: category (apps, dev, scripts, servers, services, shell, network, users, nix), root paths (patches), hosts list (emacs, server, workstation, miniserver, galaxy, vps), secrets files, proxy rules, auto-import rules, stylix/schemes, audit checklist entries, navigation links to constitution/playbooks.
Relationships: Anchors citations used by Constitution and Playbooks.

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.