From d448e0f6c8985d361df29c33c4807c8b19426b90 Mon Sep 17 00:00:00 2001
From: Danilo Reyes <danilo.reyes.251@proton.me>
Date: Fri, 30 Jan 2026 16:42:29 -0600
Subject: [PATCH] reviewing

---
 .gitignore                        |  7 ++++
 docs/constitution.md              | 52 +++++++++++++++++++++++
 docs/playbooks/add-host-toggle.md | 18 ++++++++
 docs/playbooks/add-module.md      | 18 ++++++++
 docs/playbooks/add-script.md      | 17 ++++++++
 docs/playbooks/add-secret.md      | 17 ++++++++
 docs/playbooks/add-server.md      | 18 ++++++++
 docs/playbooks/template.md        | 15 +++++++
 docs/reference/index.md           | 64 +++++++++++++++++++++++++++++
 specs/001-ai-docs/data-model.md   |  2 +-
 specs/001-ai-docs/quickstart.md   | 10 ++---
 specs/001-ai-docs/research.md     |  5 +++
 specs/001-ai-docs/tasks.md        | 68 +++++++++++++++----------------
 13 files changed, 271 insertions(+), 40 deletions(-)
 create mode 100644 docs/constitution.md
 create mode 100644 docs/playbooks/add-host-toggle.md
 create mode 100644 docs/playbooks/add-module.md
 create mode 100644 docs/playbooks/add-script.md
 create mode 100644 docs/playbooks/add-secret.md
 create mode 100644 docs/playbooks/add-server.md
 create mode 100644 docs/playbooks/template.md
 create mode 100644 docs/reference/index.md

diff --git a/.gitignore b/.gitignore
index e438614..7210bc6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,3 +7,10 @@ result
 **/secrets/*.yaml.dec
 **/*-decrypted.*
 **/temp-secrets.*
+# Editor/OS artifacts
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+*.swp
+*.tmp
diff --git a/docs/constitution.md b/docs/constitution.md
new file mode 100644
index 0000000..7eb9639
--- /dev/null
+++ b/docs/constitution.md
@@ -0,0 +1,52 @@
+# AI Constitution for the NixOS Repository
+
+## Scope and Audience
+- Audience: AI assistants and contributors needing an authoritative description of repository rules, structure, and workflows.
+- Scope: Repo-wide conventions, module categories, host roles, secrets handling, proxy rules, documentation locations, and maintenance triggers.
+- Authority: This constitution is the source of truth for AI. If human-facing docs differ, update both with the recorded resolution in `specs/001-ai-docs/research.md`.
+
+## Repository Overview
+- Architecture: Flake-based repo using `flake-parts` with inputs for pkgs (stable/unstable), stylix, home-manager, sops-nix, and service overlays. Common modules are composed through `parts/core.nix` and `parts/hosts.nix`.
+- Module auto-import: `modules/modules.nix` auto-imports `.nix` files under `modules/apps`, `modules/dev`, `modules/scripts`, `modules/servers`, `modules/services`, `modules/shell`, and `modules/network`, excluding `librewolf.nix`. Factories live in `modules/factories/` (`mkserver`, `mkscript`), and shared options are in `modules/nix` and `modules/users`.
+- Hosts and toggles: Host definitions live in `hosts/<name>/configuration.nix` with host-specific toggles in `hosts/<name>/toggles.nix`. The `my` namespace carries toggles for apps/dev/scripts/services/shell, feature flags like `enableProxy` and `enableContainers`, and per-host `interfaces` and `ips` maps.
+- Main server and proxies: `my.mainServer` selects the host that should serve traffic by default (default `miniserver`; overridden to `server` in `hosts/server/toggles.nix`). Reverse proxies use helpers in `parts/core.nix` (`proxy`, `proxyReverse`, `proxyReverseFix`, `proxyReversePrivate`) and pick IPs from `my.ips` plus the hostName/ip set by `mkserver` options.
+- Secure hosts and secrets: `my.secureHost` gates SOPS secrets. Secure hosts load secrets from `secrets/*.yaml` and wireguard definitions; non-secure hosts (e.g., `hosts/emacs`) skip secret-dependent services. Default SOPS file is `secrets/secrets.yaml` via `config/base.nix`.
+
+## Coding Conventions
+- No blank lines between code blocks; keep markdown examples tight.
+- Minimize comments; prefer clear naming and shared helpers (`modules/factories/mkserver.nix`, `modules/factories/mkscript.nix`) to avoid duplication.
+- Use business-level, technology-agnostic language in AI docs; reserve implementation detail for module code.
+
+## Terminology and Naming Standards
+- Module: A Nix module under `modules/<category>/<name>.nix` auto-imported into the system.
+- Factory: Shared option constructors in `modules/factories/` (use `mkserver` for server modules, `mkscript` for script units).
+- Options: Settings under the `my` namespace (e.g., `my.services.<service>`, `my.scripts.<script>`).
+- Toggles: Enablement maps in `hosts/<name>/toggles.nix` controlling categories (apps/dev/shell/scripts/services/servers/units) and features (`enableProxy`, `enableContainers`).
+- Servers: Reverse-proxied services under `modules/servers/`, normally created with `mkserver` options.
+- Scripts: Units defined via `mkscript` with `enable`, `install`, `service`, `users`, `timer`, and `package` fields.
+- Playbooks: Workflow guides under `docs/playbooks/` for repeatable tasks.
+- Reference map: Navigation index under `docs/reference/index.md` for paths and responsibilities.
+
+## Secrets Map and secureHost Behavior
+- Secrets files: `secrets/certs.yaml`, `secrets/env.yaml`, `secrets/gallery.yaml`, `secrets/homepage.yaml`, `secrets/keys.yaml`, `secrets/wireguard.yaml`, `secrets/secrets.yaml`, plus `secrets/ssh/` for host keys.
+- Placement rules: Keep secrets aligned to their file purpose (certificates → `certs.yaml`; environment/service env vars → `env.yaml`; media/gallery creds → `gallery.yaml`; homepage widgets → `homepage.yaml`; SSH/private keys → `keys.yaml`; WireGuard peers → `wireguard.yaml`; misc defaults → `secrets.yaml`).
+- secureHost gating: Only hosts with `my.secureHost = true` load SOPS secrets and WireGuard interfaces. Hosts with `secureHost = false` must avoid secret-dependent services and skip SOPS entries.
+
+## Module Categories and Active Hosts
+- Module categories: apps, dev, scripts, servers, services, shell, 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/<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`.
+- Conflict handling steps: identify the divergent rule, cite the source files, decide the authoritative rule per this constitution, update both the source file and the relevant doc, and record the decision and timestamp.
+
+## Maintenance Triggers and Update Process
+- Triggers: New factory/helper, new module category, new host, new toggle set, new proxy rule, new secret category/file, change to `my.mainServer` or `my.ips`, stylix scheme changes, or new auto-import filters.
+- Update flow: (1) Amend the relevant module or toggle files; (2) Update `docs/constitution.md` for rules/terminology changes; (3) Update playbooks under `docs/playbooks/` affected by the change; (4) Update `docs/reference/index.md` for navigation paths; (5) Note the decision in `specs/001-ai-docs/research.md` and refresh `quickstart.md` if discoverability shifts.
+- Validation: Confirm discoverability within two clicks (constitution → reference map/playbook), secrets map completeness, and alignment with success criteria SC-001–SC-004.
+
+## Quick Reference and Navigation
+- Constitution: `docs/constitution.md` (this file)
+- Reference map: `docs/reference/index.md` (paths, hosts, secrets, proxies, stylix)
+- Playbooks: `docs/playbooks/*.md` (add module/server/script/host toggle/secret, plus template)
+- Planning artifacts: `specs/001-ai-docs/` (plan, research, data-model, quickstart, contracts)
diff --git a/docs/playbooks/add-host-toggle.md b/docs/playbooks/add-host-toggle.md
new file mode 100644
index 0000000..6221a54
--- /dev/null
+++ b/docs/playbooks/add-host-toggle.md
@@ -0,0 +1,18 @@
+# Playbook: Add a Host Toggle
+
+- Name: Add or adjust host toggles
+- Purpose: Enable categories, services, or features per host in `hosts/<name>/toggles.nix`.
+- Prerequisites: Identify host role (see Hosts and Roles), secureHost setting, and whether proxies/containers are required.
+- Inputs: Toggle category (apps/dev/scripts/services/servers/units), users list, proxy/container flags, mainServer override, network interface names.
+- Steps:
+  1. Open `hosts/<name>/toggles.nix` and adjust category maps using helper patterns (`enableList` with `mkEnabled`, `mkEnabledWithUsers`, or `mkEnabledIp`).
+  2. Set feature flags such as `enableProxy`, `enableContainers`, and `mainServer` when the host should own proxied services.
+  3. Add service toggles under `servers` with proxy/ip data as needed; align IPs to `my.ips` (e.g., `mkEnabledIp` for remote hosts).
+  4. Ensure `interfaces` entries exist for network-facing services and match `my.interfaces` defaults unless intentionally overridden.
+  5. Reconcile toggle changes with secrets and secureHost: avoid enabling secret-backed services on hosts with `secureHost = false`.
+- Validation:
+  - Toggle sets align with host capabilities and `my.secureHost`.
+  - Proxy- or container-dependent services have `enableProxy`/`enableContainers` enabled.
+  - IP/interface values match `docs/reference/index.md` entries.
+- Outputs: Updated host toggle file reflecting new enablement and infrastructure flags.
+- References: `docs/constitution.md` (Hosts and toggles, Main server and proxies), `docs/reference/index.md` (Hosts and Roles, Proxy rules, Network maps)
diff --git a/docs/playbooks/add-module.md b/docs/playbooks/add-module.md
new file mode 100644
index 0000000..ed3ef6c
--- /dev/null
+++ b/docs/playbooks/add-module.md
@@ -0,0 +1,18 @@
+# Playbook: Add a NixOS Module
+
+- Name: Add a module under `modules/<category>/`
+- Purpose: Introduce a new module following auto-import and toggle conventions.
+- Prerequisites: Identify target host(s) and toggle category; confirm `my.secureHost` if secrets are involved.
+- Inputs: Module name, category (apps/dev/scripts/servers/services/shell/network), required options, secret needs, proxy requirements if server-facing.
+- Steps:
+  1. Choose the category path from `docs/reference/index.md` and create `modules/<category>/<name>.nix` (auto-import picks it up; avoid names filtered out such as `librewolf.nix`).
+  2. Define options under `my.<category>` or reuse factories (`mkserver` for servers, `mkscript` for scripts) instead of hand-rolled patterns.
+  3. If the module needs secrets, guard references with `lib.mkIf config.my.secureHost` and map them to the correct secrets file (see secrets map).
+  4. For networked services, align host selection with `my.mainServer` and `my.ips`; enable reverse proxy via `enableProxy` when applicable.
+  5. Wire toggles for target hosts in `hosts/<host>/toggles.nix`, ensuring users/groups and containers/proxy flags are set.
+- Validation:
+  - Module loads without extra imports (auto-import applies).
+  - Toggle wiring matches intended hosts; secureHost gating present for secrets.
+  - Proxy and port choices align with `my.mainServer`, `my.ips`, and firewall rules.
+- Outputs: New module file and updated host toggles if required.
+- References: `docs/constitution.md` (Module Categories, Secrets Map, Main server and proxies), `docs/reference/index.md` (Module Directories, Proxy rules, Secrets Map)
diff --git a/docs/playbooks/add-script.md b/docs/playbooks/add-script.md
new file mode 100644
index 0000000..244c79d
--- /dev/null
+++ b/docs/playbooks/add-script.md
@@ -0,0 +1,17 @@
+# Playbook: Add a Script Unit
+
+- Name: Add a script via `mkscript`
+- Purpose: Ship a script package with optional user service and timer.
+- Prerequisites: Identify target users (`my.toggleUsers.scripts` defaults), secureHost status if the script needs secrets, and whether a timer/service is required.
+- Inputs: Script name, package derivation, description, timer schedule, users list, service needs.
+- Steps:
+  1. Add a definition under `my.scripts.<name>` in `modules/scripts/<name>.nix` using `mkscript` options (`enable`, `install`, `service`, `users`, `timer`, `package`, `description`).
+  2. Ensure the package exposes the executable name used by the service/timer.
+  3. For user scoping, set `users` to a single user or list; defaults come from `my.toggleUsers.scripts`.
+  4. If secrets are required, guard references with `lib.mkIf config.my.secureHost` and map them to the appropriate secrets file.
+  5. Enable the script toggle in `hosts/<host>/toggles.nix` under `scripts` or `units`, and ensure timers/services are expected on that host.
+- Validation:
+  - Script installs for intended users; systemd user service/timer activates only when `enable` and `service` are true.
+  - secureHost gating present for any secrets; no orphaned timers.
+- Outputs: New script module and updated host toggles if needed.
+- References: `docs/constitution.md` (Terminology, Secrets Map), `docs/reference/index.md` (Module Directories, Secrets Map, Hosts and Roles)
diff --git a/docs/playbooks/add-secret.md b/docs/playbooks/add-secret.md
new file mode 100644
index 0000000..c4776c2
--- /dev/null
+++ b/docs/playbooks/add-secret.md
@@ -0,0 +1,17 @@
+# Playbook: Add a Secret Entry
+
+- Name: Add or update a secret
+- Purpose: Place secrets in the correct SOPS file with secureHost gating.
+- Prerequisites: Target host(s) must have `my.secureHost = true`; identify secret type and consumer service/module.
+- Inputs: Secret name, target file (certs/env/gallery/homepage/keys/wireguard/secrets), owner/group if file material is written, consuming module path.
+- Steps:
+  1. Choose the correct secrets file from the map in `docs/constitution.md` and add the entry there (YAML, encrypted via sops-nix).
+  2. If a private key or file path is required, specify `owner`, `group`, and target path consistent with the consuming module.
+  3. In the consuming module, reference the secret under `config.sops.secrets.<name>` and guard with `lib.mkIf config.my.secureHost`.
+  4. For WireGuard entries, update `secrets/wireguard.yaml` and corresponding interface configuration under the target host.
+  5. Avoid adding secrets for hosts with `secureHost = false`; instead route the workload to a secure host or skip enablement.
+- Validation:
+  - Secret lives in the correct file and encrypts with SOPS; file ownership matches service user where applicable.
+  - Module references are gated by `secureHost` and align with host toggles.
+- Outputs: Updated secrets file and gated module references.
+- References: `docs/constitution.md` (Secrets Map and secureHost), `docs/reference/index.md` (Secrets Map, Hosts and Roles)
diff --git a/docs/playbooks/add-server.md b/docs/playbooks/add-server.md
new file mode 100644
index 0000000..adac787
--- /dev/null
+++ b/docs/playbooks/add-server.md
@@ -0,0 +1,18 @@
+# Playbook: Add a Server Module with mkserver
+
+- Name: Add a reverse-proxied server module
+- Purpose: Stand up a server using `modules/factories/mkserver.nix` with correct proxy and host routing.
+- Prerequisites: Target host must have `my.enableProxy = true` and container support if needed; confirm `my.secureHost` for secrets.
+- Inputs: Service name, desired subdomain, port, proxy type (standard/fix/private), cron needs, secrets/env vars.
+- Steps:
+  1. Create `modules/servers/<name>.nix` and import `mkserver` options to define `enable`, `enableProxy`, `port`, `host`, `hostName`, `url`, `ip`, `enableSocket`, and `certPath` as needed.
+  2. Default host routing uses `my.mainServer` and `my.ips`; override `hostName`/`ip` only when the service must live elsewhere.
+  3. For reverse proxy behavior, select helper from `parts/core.nix`: `proxyReverse` (standard), `proxyReverseFix` (preserve host headers/websockets), or `proxyReversePrivate` (mutual TLS).
+  4. Place secrets/env references in the appropriate file from the secrets map and guard with `lib.mkIf config.my.secureHost`.
+  5. Enable the service toggle in `hosts/<host>/toggles.nix` under `servers` (and `enableProxy` if not already set); add any firewall/static ports needed.
+- Validation:
+  - Service resolves to the expected URL and IP per `my.ips` and `my.mainServer`.
+  - Proxy helper matches the protocol needs; SSL settings align with cert sources.
+  - Secrets load only on secure hosts; firewall assertions pass.
+- Outputs: New server module with mkserver options and updated host toggles/firewall settings.
+- References: `docs/constitution.md` (Main server and proxies, Secrets Map), `docs/reference/index.md` (Proxy rules, Module Directories, Secrets Map, Hosts and Roles)
diff --git a/docs/playbooks/template.md b/docs/playbooks/template.md
new file mode 100644
index 0000000..c1711bb
--- /dev/null
+++ b/docs/playbooks/template.md
@@ -0,0 +1,15 @@
+# Playbook Template
+
+- Name:
+- Purpose:
+- Prerequisites: (toggles, hosts, secureHost, required secrets)
+- Inputs: (paths, options, credentials, ports)
+- Steps:
+  1. 
+  2. 
+  3. 
+- Validation:
+  - 
+  - 
+- Outputs:
+- References: `docs/constitution.md` (relevant sections) and `docs/reference/index.md` (paths/hosts/proxies/secrets)
diff --git a/docs/reference/index.md b/docs/reference/index.md
new file mode 100644
index 0000000..3a92285
--- /dev/null
+++ b/docs/reference/index.md
@@ -0,0 +1,64 @@
+# Reference Map
+
+## Module Directories
+- apps → `modules/apps/` (desktop/workstation apps, auto-imported)
+- dev → `modules/dev/` (language toolchains and dev shells, auto-imported)
+- scripts → `modules/scripts/` (script units built via `mkscript`, auto-imported)
+- servers → `modules/servers/` (reverse-proxied services built via `mkserver`)
+- services → `modules/services/` (supporting services like syncthing, wireguard)
+- shell → `modules/shell/` (shell customizations and CLI tooling)
+- 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)
+
+## 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.
+
+## Hosts and Roles
+- Configs: `hosts/<name>/configuration.nix` with toggles in `hosts/<name>/toggles.nix`.
+- Active hosts: `workstation`, `server`, `miniserver`, `galaxy`, `emacs`.
+- Roles:
+  - workstation: developer desktop; provides build power for distributed builds.
+  - server: primary services host (overrides `my.mainServer = "server"` and enables proxies/containers).
+  - miniserver: small-footprint server; default `mainServer` in shared options.
+  - galaxy: small server variant using nixpkgs-small.
+  - emacs: VM profile, `my.secureHost = false` for secret-free usage.
+- Network maps: `my.ips` and `my.interfaces` declared in `modules/modules.nix`; host toggles may override.
+
+## Proxy, Firewall, and Networking
+- Proxy enablement: `my.enableProxy` toggles Nginx reverse proxy; assertions require at least one `my.servers.*.enableProxy` when enabled.
+- Proxy helpers: use `parts/core.nix` helpers (`proxy`, `proxyReverse`, `proxyReverseFix` for header preservation, `proxyReversePrivate` for mutual TLS). `mkserver` supplies `host`, `ip`, `url`, and `enableProxy` defaults per service.
+- Main server selection: `my.mainServer` chooses where services live by default; `mkserver` sets `isLocal` based on this and picks IPs from `my.ips`.
+- Firewall generation: `inputs.self.lib.generateFirewallPorts` combines static ports, additional ports, and service ports from `my.servers` (excluding native firewall services). Use `my.network.firewall` settings and `getServicesWithNativeFirewall` to derive open ports.
+
+## Secrets Map
+- Files and purposes:
+  - `secrets/certs.yaml` → certificates and TLS material.
+  - `secrets/env.yaml` → environment variables for services (e.g., lidarr-mb-gap).
+  - `secrets/gallery.yaml` → media/gallery credentials.
+  - `secrets/homepage.yaml` → homepage widget secrets.
+  - `secrets/keys.yaml` → SSH/private keys and key ownership.
+  - `secrets/wireguard.yaml` → WireGuard peers and private keys.
+  - `secrets/secrets.yaml` → default SOPS file (general secrets, fallback when unspecified).
+  - `secrets/ssh/` → host SSH keys and related artifacts.
+- secureHost: Only hosts with `my.secureHost = true` consume SOPS entries and WireGuard interfaces. Keep secret references behind `lib.mkIf config.my.secureHost`.
+
+## Stylix and Theming
+- Stylix module: `config/stylix.nix` and stylix inputs in `flake.nix` apply theming. Host toggle `my.stylix.enable` controls activation (see host toggles).
+- Schemes and assets: Imported via Stylix inputs; wallpapers/fonts sourced from external flakes (`wallpapers`, `fonts`).
+
+## Playbooks and Templates
+- Playbook template: `docs/playbooks/template.md`
+- Workflows: `docs/playbooks/add-module.md`, `add-server.md`, `add-script.md`, `add-host-toggle.md`, `add-secret.md`
+- Constitution link-back: `docs/constitution.md` sections on terminology, proxies, secrets, and maintenance.
+
+## Quick Audit Checklist
+- Module coverage: All categories (apps, dev, scripts, servers, services, shell, network, users, nix, patches) have corresponding entries and auto-import rules.
+- 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.
+- Discoverability: Paths reachable within two clicks from `docs/constitution.md`.
diff --git a/specs/001-ai-docs/data-model.md b/specs/001-ai-docs/data-model.md
index c26af95..6628e5c 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), 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
diff --git a/specs/001-ai-docs/quickstart.md b/specs/001-ai-docs/quickstart.md
index 01aa731..debf59d 100644
--- a/specs/001-ai-docs/quickstart.md
+++ b/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`.
diff --git a/specs/001-ai-docs/research.md b/specs/001-ai-docs/research.md
index 37111f2..db7f625 100644
--- a/specs/001-ai-docs/research.md
+++ b/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).
diff --git a/specs/001-ai-docs/tasks.md b/specs/001-ai-docs/tasks.md
index 8a1fb26..51ef6bf 100644
--- a/specs/001-ai-docs/tasks.md
+++ b/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/)
 
 ---