From 7671ec686fe5e9bb0103a84d5e3c49bb0820d6b5 Mon Sep 17 00:00:00 2001 From: Danilo Reyes Date: Fri, 6 Feb 2026 22:58:20 -0600 Subject: [PATCH] documentation audit --- docs/constitution.md | 4 ++-- docs/reference/index.md | 7 ++++--- specs/001-ai-docs/data-model.md | 2 +- specs/001-ai-docs/research.md | 5 +++++ specs/001-ai-docs/spec.md | 2 +- 5 files changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/constitution.md b/docs/constitution.md index c5cd20c..85cc887 100644 --- a/docs/constitution.md +++ b/docs/constitution.md @@ -46,8 +46,8 @@ config.services = { - VPS enrollment flow: The vps host generates its own key on first boot, then operators enroll the public key, re-encrypt secrets, and redeploy. Follow `docs/playbooks/enroll-vps.md`. ## Module Categories and Active Hosts -- Module categories: apps, dev, scripts, servers, services, shell, websites, network, users, nix, patches. Factories sit in `modules/factories/` and are imported explicitly. -- Active hosts: `workstation`, `server`, `miniserver`, `galaxy`, `emacs`. Host roles and secure status are defined in `hosts//configuration.nix` and toggles in `hosts//toggles.nix`. +- Module categories: apps, dev, scripts, servers, services, shell, websites, network, users, nix. Factories sit in `modules/factories/` and are imported explicitly; patch artifacts live at the repo root in `patches/`. +- Active hosts: `workstation`, `server`, `miniserver`, `galaxy`, `emacs`, `vps`. Host roles and secure status are defined in `hosts//configuration.nix` and toggles in `hosts//toggles.nix`. ## Precedence and Conflict Resolution - Precedence: This constitution is authoritative for AI. Human docs must be updated to match. If conflicts are found, align human docs to the constitution and log the resolution in `specs/001-ai-docs/research.md`. diff --git a/docs/reference/index.md b/docs/reference/index.md index d21c6b7..f38f407 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -11,13 +11,14 @@ - network → `modules/network/` (networking rules, firewall helpers) - users → `modules/users/` (user-related options) - nix → `modules/nix/` (Nix configuration and helpers) -- patches → `patches/` (patch artifacts referenced by modules) - factories → `modules/factories/` (`mkserver.nix`, `mkscript.nix` shared helpers) +## Root Directories +- patches → `patches/` (patch artifacts referenced by modules) ## Auto-Import Rules - Source: `modules/modules.nix` uses `inputs.self.lib.autoImport` to load `.nix` files from module directories. - Filter: Excludes `librewolf.nix`; all other `.nix` files in target dirs are loaded automatically. -- Implication: Place new modules in the correct category directory with a `.nix` filename; no manual import wiring required unless adding a new factory. +- Implication: Place new modules in the correct category directory with a `.nix` filename; no manual import wiring required unless adding a new factory. Patch artifacts under `patches/` are not auto-imported. ## Hosts and Roles - Configs: `hosts//configuration.nix` with toggles in `hosts//toggles.nix`. @@ -61,7 +62,7 @@ - MCP server reference: `docs/reference/mcp-server.md` (tool catalog, `nixos-mcp` wrapper, invocation, sync-docs) ## Quick Audit Checklist -- Module coverage: All categories (apps, dev, scripts, servers, services, shell, websites, network, users, nix, patches) have corresponding entries and auto-import rules. +- Module coverage: All categories (apps, dev, scripts, servers, services, shell, websites, network, users, nix) have corresponding entries and auto-import rules; `patches/` is documented as a root directory. - Host coverage: Active hosts listed with roles and secureHost status; `mainServer` noted. - Proxy rules: `enableProxy` usage, proxy helper selection, and `my.ips` mappings documented. - Secrets map: Every secrets file and secureHost gating captured; new secret types aligned to file purposes. diff --git a/specs/001-ai-docs/data-model.md b/specs/001-ai-docs/data-model.md index 6628e5c..e88573f 100644 --- a/specs/001-ai-docs/data-model.md +++ b/specs/001-ai-docs/data-model.md @@ -14,7 +14,7 @@ ### Reference Map - **Role**: Index mapping core concerns to repo paths for navigation and validation. -- **Key Fields**: category (apps, dev, scripts, servers, services, shell, network, users, nix, patches), hosts list (emacs, server, workstation, miniserver, galaxy), secrets files, proxy rules, auto-import rules, stylix/schemes, audit checklist entries, navigation links to constitution/playbooks. +- **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. ## Constraints and States diff --git a/specs/001-ai-docs/research.md b/specs/001-ai-docs/research.md index 2939c3e..a618a2c 100644 --- a/specs/001-ai-docs/research.md +++ b/specs/001-ai-docs/research.md @@ -29,3 +29,8 @@ - **Decision**: Gate SOPS configuration behind `config.my.secureHost` so non-secure hosts skip secret loading. - **Rationale**: Aligns `config/base.nix` behavior with the constitution’s secureHost rules and avoids secret dependency on non-secure hosts. - **Alternatives considered**: (a) Leave SOPS enabled on all hosts (rejected: violates secureHost contract); (b) Duplicate SOPS logic per host (rejected: increases drift risk). + +## Decision 7 (2026-02-07): Module categories and patches location; active hosts update +- **Decision**: Treat `patches/` as a root-level directory (not a module category) and update active hosts to include `vps`. +- **Rationale**: Repo structure places patches at the root and hosts include `vps`; documentation must reflect actual paths and host inventory. +- **Alternatives considered**: (a) Move `patches/` under `modules/` (rejected: would change repo layout); (b) Keep `vps` undocumented (rejected: causes host list drift). diff --git a/specs/001-ai-docs/spec.md b/specs/001-ai-docs/spec.md index beee7bc..afb53d7 100644 --- a/specs/001-ai-docs/spec.md +++ b/specs/001-ai-docs/spec.md @@ -89,6 +89,6 @@ An AI or contributor can update the constitution and use-case docs when repo rul ### Measurable Outcomes - **SC-001**: An AI with only these docs can describe the correct steps and file locations to add a new server module in under 2 minutes of reading time, matching existing patterns. -- **SC-002**: The constitution explicitly enumerates 100% of current module categories (apps, dev, scripts, servers, services, shell, network, users, nix, patches) and active hosts (emacs, server, workstation) with their roles. +- **SC-002**: The constitution explicitly enumerates 100% of current module categories (apps, dev, scripts, servers, services, shell, network, users, nix), documents the root `patches/` directory, and lists active hosts (emacs, server, workstation, miniserver, galaxy, vps) with their roles. - **SC-003**: Guidance includes the full secrets file map (certs/env/gallery/homepage/keys/wireguard/secrets) and secureHost behavior with no omissions when audited against the repository. - **SC-004**: Playbook locations and required fields are discoverable via the documented index in ≤2 navigation steps from the top of the spec.