reviewing

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), secrets files, proxy rules, auto-import rules, stylix/schemes.
+- **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.
 - **Relationships**: Anchors citations used by Constitution and Playbooks.
 
 ## Constraints and States

specs/001-ai-docs/quickstart.md

@@ -1,7 +1,7 @@
 # Quickstart: AI-Facing Repository Constitution
 
-1) Read the constitution (`docs/constitution.md`) to understand repo rules, conventions, and precedence for AI.
-2) Use the reference map (`docs/reference/index.md`) to locate relevant paths (module categories, hosts, secrets files, proxy rules, stylix schemes).
-3) Follow the appropriate use-case playbook (adding module/server/script/host/secrets) under `docs/playbooks/`; ensure steps reference helpers (e.g., mkserver) and secrets placement.
-4) Validate against the checklist: full category/host coverage, secrets map completeness, discoverability within two navigation steps, constitution precedence defined.
-5) When repo structure or rules change, update constitution, playbooks, and reference map together, logging the decision in Clarifications.
+1) Start with the constitution at `docs/constitution.md` for scope, terminology, proxies, secrets map, and precedence (constitution overrides human docs for AI).
+2) Navigate with the reference map at `docs/reference/index.md` (module directories, hosts/roles, auto-import filters, proxy helpers, secrets map, stylix).
+3) Run the correct playbook from `docs/playbooks/` (`add-module`, `add-server`, `add-script`, `add-host-toggle`, `add-secret`) and keep secureHost gating in mind.
+4) Validate outcomes using the audit checklist in `docs/reference/index.md` (coverage of categories/hosts, secrets completeness, proxy rules, discoverability ≤2 steps).
+5) If rules or structure change: update `docs/constitution.md`, refresh affected playbooks and `docs/reference/index.md`, then record the decision and date in `specs/001-ai-docs/research.md`.

specs/001-ai-docs/research.md

@@ -14,3 +14,8 @@
 - **Decision**: Validate docs manually against repo conventions and the specification’s success criteria (discoverability ≤2 steps, full module/host coverage, secrets map completeness).
 - **Rationale**: No automated tests for markdown; checklist-based review matches spec.
 - **Alternatives considered**: (a) Add automated linting now (rejected: out-of-scope for this documentation feature); (b) No validation (rejected: risks drift and omissions).
+
+## Decision 4: Navigation and conflict logging
+- **Decision**: Anchor discoverability through `docs/constitution.md` with links to `docs/reference/index.md` and `docs/playbooks/`; record any conflict resolutions in `specs/001-ai-docs/research.md` with date and source references.
+- **Rationale**: Keeps navigation within two steps for AI and centralizes historical decisions for reconciliation.
+- **Alternatives considered**: (a) Distribute links per playbook only (rejected: harder to enforce two-step navigation); (b) Log conflicts in ad-hoc comments (rejected: loses traceability for AI tools).

specs/001-ai-docs/tasks.md

@@ -23,10 +23,10 @@
 
 **Purpose**: Prepare documentation scaffolding and locations.
 
-- [ ] T001 Create `docs/` constitution folder structure per plan (docs/)
-- [ ] T002 Create `docs/` playbooks subfolder for workflows (docs/playbooks/)
-- [ ] T003 Create `docs/` reference-map subfolder for indexes (docs/reference/)
-- [ ] T004 Link feature artifacts index in specs/001-ai-docs/quickstart.md to future docs/ locations (specs/001-ai-docs/quickstart.md)
+- [X] T001 Create `docs/` constitution folder structure per plan (docs/)
+- [X] T002 Create `docs/` playbooks subfolder for workflows (docs/playbooks/)
+- [X] T003 Create `docs/` reference-map subfolder for indexes (docs/reference/)
+- [X] T004 Link feature artifacts index in specs/001-ai-docs/quickstart.md to future docs/ locations (specs/001-ai-docs/quickstart.md)
 
 ---
 
@@ -34,10 +34,10 @@
 
 **Purpose**: Shared artifacts all user stories rely on.
 
-- [ ] T005 Draft constitution outline with required sections and precedence statement (docs/constitution.md)
-- [ ] T006 Populate secrets map structure and secureHost rules placeholder (docs/constitution.md)
-- [ ] T007 Add reference map skeleton covering modules, hosts, secrets, proxies, stylix (docs/reference/index.md)
-- [ ] T008 Add playbook template covering required fields (docs/playbooks/template.md)
+- [X] T005 Draft constitution outline with required sections and precedence statement (docs/constitution.md)
+- [X] T006 Populate secrets map structure and secureHost rules placeholder (docs/constitution.md)
+- [X] T007 Add reference map skeleton covering modules, hosts, secrets, proxies, stylix (docs/reference/index.md)
+- [X] T008 Add playbook template covering required fields (docs/playbooks/template.md)
 
 **Checkpoint**: Foundation ready - user story implementation can now begin in parallel.
 
@@ -51,14 +51,14 @@
 
 ### Implementation for User Story 1
 
-- [ ] T009 [US1] Fill constitution scope, audience, repo overview (flake-parts, auto-imports, hosts/toggles, mainServer/proxy rules) (docs/constitution.md)
-- [ ] T010 [US1] Document coding conventions (no blank lines between blocks, comment discipline, factor duplication via functions/factories) (docs/constitution.md)
-- [ ] T011 [US1] Define canonical terminology and naming standards for modules, factories, options, toggles, servers, scripts, playbooks (docs/constitution.md)
-- [ ] T012 [US1] Document secrets map and secureHost behavior (certs/env/gallery/homepage/keys/wireguard/secrets) (docs/constitution.md)
-- [ ] T013 [US1] Enumerate module categories and active hosts with roles (docs/constitution.md)
-- [ ] T014 [US1] Add precedence/conflict resolution section (constitution over human docs for AI) (docs/constitution.md)
-- [ ] T015 [US1] Add maintenance triggers and update process (docs/constitution.md)
-- [ ] T016 [US1] Add quick-reference index linking to playbooks and reference map (docs/constitution.md)
+- [X] T009 [US1] Fill constitution scope, audience, repo overview (flake-parts, auto-imports, hosts/toggles, mainServer/proxy rules) (docs/constitution.md)
+- [X] T010 [US1] Document coding conventions (no blank lines between blocks, comment discipline, factor duplication via functions/factories) (docs/constitution.md)
+- [X] T011 [US1] Define canonical terminology and naming standards for modules, factories, options, toggles, servers, scripts, playbooks (docs/constitution.md)
+- [X] T012 [US1] Document secrets map and secureHost behavior (certs/env/gallery/homepage/keys/wireguard/secrets) (docs/constitution.md)
+- [X] T013 [US1] Enumerate module categories and active hosts with roles (docs/constitution.md)
+- [X] T014 [US1] Add precedence/conflict resolution section (constitution over human docs for AI) (docs/constitution.md)
+- [X] T015 [US1] Add maintenance triggers and update process (docs/constitution.md)
+- [X] T016 [US1] Add quick-reference index linking to playbooks and reference map (docs/constitution.md)
 
 **Checkpoint**: Constitution stands alone for AI queries.
 
@@ -72,13 +72,13 @@
 
 ### Implementation for User Story 2
 
-- [ ] T017 [US2] Write playbook for adding a NixOS module (docs/playbooks/add-module.md)
-- [ ] T018 [US2] Write playbook for adding a server module using mkserver (docs/playbooks/add-server.md)
-- [ ] T019 [US2] Write playbook for adding a script unit (docs/playbooks/add-script.md)
-- [ ] T020 [US2] Write playbook for adding a host toggle and host wiring (docs/playbooks/add-host-toggle.md)
-- [ ] T021 [US2] Write playbook for secrets entry mapping to files (docs/playbooks/add-secret.md)
-- [ ] T022 [US2] Fill reference map entries for module dirs, auto-import filters, proxy types, firewall generation, stylix schemes, hosts (docs/reference/index.md)
-- [ ] T023 [US2] Link playbooks and reference map from constitution index (docs/constitution.md)
+- [X] T017 [US2] Write playbook for adding a NixOS module (docs/playbooks/add-module.md)
+- [X] T018 [US2] Write playbook for adding a server module using mkserver (docs/playbooks/add-server.md)
+- [X] T019 [US2] Write playbook for adding a script unit (docs/playbooks/add-script.md)
+- [X] T020 [US2] Write playbook for adding a host toggle and host wiring (docs/playbooks/add-host-toggle.md)
+- [X] T021 [US2] Write playbook for secrets entry mapping to files (docs/playbooks/add-secret.md)
+- [X] T022 [US2] Fill reference map entries for module dirs, auto-import filters, proxy types, firewall generation, stylix schemes, hosts (docs/reference/index.md)
+- [X] T023 [US2] Link playbooks and reference map from constitution index (docs/constitution.md)
 
 **Checkpoint**: Playbooks and reference map make placement and schema discoverable.
 
@@ -92,11 +92,11 @@
 
 ### Implementation for User Story 3
 
-- [ ] T024 [US3] Add maintenance triggers list (new factory/helper, new secret category, new toggle, new host/module dir) (docs/constitution.md)
-- [ ] T025 [US3] Add update workflow/checklist for constitution, playbooks, reference map (docs/constitution.md)
-- [ ] T026 [US3] Add conflict-resolution steps and logging guidance in constitution (docs/constitution.md)
-- [ ] T027 [US3] Add quick audit checklist to reference map for drift detection (docs/reference/index.md)
-- [ ] T028 [US3] Update quickstart.md with maintenance flow summary (specs/001-ai-docs/quickstart.md)
+- [X] T024 [US3] Add maintenance triggers list (new factory/helper, new secret category, new toggle, new host/module dir) (docs/constitution.md)
+- [X] T025 [US3] Add update workflow/checklist for constitution, playbooks, reference map (docs/constitution.md)
+- [X] T026 [US3] Add conflict-resolution steps and logging guidance in constitution (docs/constitution.md)
+- [X] T027 [US3] Add quick audit checklist to reference map for drift detection (docs/reference/index.md)
+- [X] T028 [US3] Update quickstart.md with maintenance flow summary (specs/001-ai-docs/quickstart.md)
 
 **Checkpoint**: Maintenance and conflict resolution are documented and repeatable.
 
@@ -106,12 +106,12 @@
 
 **Purpose**: Final alignment and validation across documents.
 
-- [ ] T029 [P] Cross-check constitution, playbooks, reference map against SC-001–SC-004 and FR-008 (docs/constitution.md, docs/playbooks/, docs/reference/index.md)
-- [ ] T030 [P] Ensure discoverability ≤2 navigation steps from top-level docs (docs/)
-- [ ] T031 [P] Validate business-level, tech-agnostic language per FR-008 across all docs (docs/)
-- [ ] T032 [P] Update specs/001-ai-docs/research.md with any decisions made during authoring (specs/001-ai-docs/research.md)
-- [ ] T033 [P] Update specs/001-ai-docs/data-model.md if entities/fields changed (specs/001-ai-docs/data-model.md)
-- [ ] T034 Final proofread and format pass (docs/)
+- [X] T029 [P] Cross-check constitution, playbooks, reference map against SC-001–SC-004 and FR-008 (docs/constitution.md, docs/playbooks/, docs/reference/index.md)
+- [X] T030 [P] Ensure discoverability ≤2 navigation steps from top-level docs (docs/)
+- [X] T031 [P] Validate business-level, tech-agnostic language per FR-008 across all docs (docs/)
+- [X] T032 [P] Update specs/001-ai-docs/research.md with any decisions made during authoring (specs/001-ai-docs/research.md)
+- [X] T033 [P] Update specs/001-ai-docs/data-model.md if entities/fields changed (specs/001-ai-docs/data-model.md)
+- [X] T034 Final proofread and format pass (docs/)
 
 ---