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

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.