# Reference Map

## Module Directories
- apps → `modules/apps/` (desktop/workstation apps; supports legacy flat modules and preferred split feature directories)
- dev → `modules/dev/` (language toolchains and dev shells; supports legacy flat modules and preferred split feature directories)
- scripts → `modules/scripts/` (script units built via `mkscript`; supports legacy flat modules and preferred split feature directories)
- servers → `modules/servers/` (reverse-proxied services built via `mkserver`; supports legacy flat modules and preferred split feature directories)
- services → `modules/services/` (supporting services like syncthing, wireguard; supports legacy flat modules and preferred split feature directories)
- shell → `modules/shell/` (shell customizations and CLI tooling; supports legacy flat modules and preferred split feature directories)
- websites → `modules/websites/` (static nginx vhosts for portfolio/blog and reports; supports legacy flat modules and preferred split feature directories)
- network → `modules/network/` (networking rules, firewall helpers; supports legacy flat modules and preferred split feature directories)
- users → `modules/users/` (user-related options)
- nix → `modules/nix/` (Nix configuration and helpers)
- factories → `modules/factories/` (`mkserver.nix`, `mkscript.nix` shared helpers)
- home-manager loader → `modules/home-manager.nix` (discovers nested `home.nix` files under `modules/`)
## Root Directories
- patches → `patches/` (patch artifacts referenced by modules)

## User Config Split
- System-side user config: `config/<name>.nix` for NixOS user accounts, host secrets, groups, and other OS-owned state.
- Home-side user config: `config/<name>-home.nix` for Home Manager-only files, shell/program configuration, and per-user match blocks.
- Current example: `config/jawz.nix` and `config/jawz-home.nix`.

## Auto-Import Rules
- Source: `modules/modules.nix` uses `inputs.self.lib.autoImport` for legacy flat `.nix` files and `inputs.self.lib.autoImportLeaf` for nested `nixos.nix` files.
- Home Manager source: `config/base.nix` registers `modules/home-manager.nix` in `home-manager.sharedModules`, and that module uses `inputs.self.lib.autoImportLeaf` to discover nested `home.nix` files anywhere under `modules/`.
- Filter: Legacy flat auto-import excludes `librewolf.nix`; nested split modules are discovered by exact leaf name (`nixos.nix` or `home.nix`).
- Preferred layout: `modules/<category>/<name>/nixos.nix` and `modules/<category>/<name>/home.nix`.
- Migration rule: Legacy flat `modules/<category>/<name>.nix` modules remain supported while features are moved into split directories.
- Implication: Place new dual-surface modules in a feature directory so NixOS and Home Manager stay adjacent; no manual import wiring is required unless adding a new factory.

## Home Manager Helpers
- Shared helper home: `parts/core.nix` exports reusable Home Manager helper functions through `inputs.self.lib`.
- Current helpers:
  - `hmModule` → derive default HM enablement from `osConfig.my.<path>` and the current Home Manager username.
  - `hmShellType` → resolve `bash` vs `zsh` consistently for HM modules with or without `osConfig`.
  - `hmOnlyUser` → gate HM snippets to a specific username when a feature is intentionally user-specific.
- Usage rule: Use these helpers for repeated wrapper logic; keep feature-specific package sets and config payloads in local `common.nix` or `home.nix` files.

## Hosts and Roles
- Configs: `hosts/<name>/configuration.nix` with toggles in `hosts/<name>/toggles.nix`.
- Active hosts: `workstation`, `server`, `miniserver`, `galaxy`, `emacs`, `vps`.
- Roles:
  - workstation: developer desktop; provides build power for distributed builds.
  - server: primary services host; runs most services and WireGuard targets.
  - miniserver: small-footprint server.
  - galaxy: small server variant using nixpkgs-small.
  - emacs: VM profile, `my.secureHost = false` for secret-free usage.
  - vps: Linode VPS image target, secure host with enrollment-based secrets.
- 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`, `enableProxy`, and `useDefaultProxy`.
- Default proxying: any server with `enableProxy = true` gets a `proxyReverse` vhost unless `useDefaultProxy = false` or it is listed in `proxyReverseFix` / `proxyReversePrivate`.
- Main server selection: `my.mainServer` chooses where services live by default (default `vps`); `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`; proxy-only services that use private certs must still declare their cert secrets when `enableProxy = true`.

## 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`
- Playbook: `docs/playbooks/add-module.md` — add a module in the right category and confirm auto-import.
- Playbook: `docs/playbooks/split-home-manager.md` — migrate a mixed module into paired `nixos.nix` and `home.nix` files.
- Playbook: `docs/playbooks/add-server.md` — add a reverse-proxied server via `mkserver` and proxy rules.
- Playbook: `docs/playbooks/add-script.md` — add a script unit via `mkscript` with install/service/timer options.
- Playbook: `docs/playbooks/add-host-toggle.md` — add or update host toggle maps under `hosts/<name>/toggles.nix`.
- Playbook: `docs/playbooks/add-secret.md` — add a SOPS secret in the correct file and wire it into modules.
- Playbook: `docs/playbooks/add-wireguard-peer.md` — add a WireGuard peer and update secrets/hosts.
- Playbook: `docs/playbooks/enroll-vps.md` — enroll a VPS key, re-encrypt secrets, redeploy.
- Playbook: `docs/playbooks/vps-rebuild.md` — rebuild the VPS with the expected deploy flow.
- Constitution link-back: `docs/constitution.md` sections on terminology, proxies, secrets, and maintenance.
- 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) have corresponding entries and auto-import rules for both legacy flat modules and split `nixos.nix`/`home.nix` modules; `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.
- Discoverability: Paths reachable within two clicks from `docs/constitution.md`.