# Documentation Contract: AI-Facing Repository Constitution

## Constitution Document
- **Purpose**: Authoritative AI guide for repo rules, architecture, conventions, and precedence.
- **Required Sections**:
  - Scope and audience (AI tools)
  - Repo overview (flake-parts, auto-imported modules, hosts/toggles, mainServer/proxy rules)
  - Coding conventions (no blank lines between blocks, minimal comments, factor duplication via functions/factories)
  - Secrets map (certs/env/gallery/homepage/keys/wireguard/secrets) and secureHost behavior
  - Active hosts and module categories coverage
  - Precedence and conflict resolution (constitution over human docs for AI)
  - Maintenance triggers and update process
  - Quick-reference index linking to repo paths and playbooks

## Use-case Playbooks
- **Purpose**: Step-by-step workflows for common tasks (add module/server/script/host/secrets).
- **Required Fields**: Name, prerequisites (toggles/hosts/secureHost), inputs, steps, outputs, references to helpers (e.g., mkserver, auto-import), secrets placement, validation checklist.
- **Location**: `/docs` (linked) or `/specs/001-ai-docs` as interim until promoted.

## Reference Map
- **Purpose**: Index for navigation.
- **Required Fields**: Category → repo path(s), notes on auto-import filters, proxy type mapping, firewall rules generation, stylix schemes location, active hosts.

## Validation
- **Checklist Alignment**: Must satisfy feature success criteria (coverage completeness, discoverability ≤2 steps, secrets map completeness).
- **Review**: Manual review against requirements and this contract; record conflicts and resolutions.