documentation audit

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.
+- 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`. Host roles and secure status are defined in `hosts/<name>/configuration.nix` and toggles in `hosts/<name>/toggles.nix`.
+- Active hosts: `workstation`, `server`, `miniserver`, `galaxy`, `emacs`, `vps`. Host roles and secure status are defined in `hosts/<name>/configuration.nix` and toggles in `hosts/<name>/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`.

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/<name>/configuration.nix` with toggles in `hosts/<name>/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.

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

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).

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.