27 lines
1.6 KiB
Markdown
27 lines
1.6 KiB
Markdown
# 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.
|