init

specs/001-ai-docs/contracts/docs-contract.md

@@ -0,0 +1,26 @@
+# 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.