instructions files

.github/instructions/host-naming-report.md

@@ -0,0 +1,68 @@
+# Host Naming Discrepancy Report
+
+This report compares the current `modules/hosts` tree against the naming rules for new hosts in `hosts.instructions.md`.
+
+## Rules Checked
+
+- The host directory slug should be the canonical host identity.
+- A directory-backed host should prefer `default.nix` as its main entrypoint.
+- The canonical slug should line up with the primary `hostname` binding, `flake.nixosConfigurations.<slug>`, and `networking.hostName`.
+- A host-local Home Manager module should use the same slug.
+- A standalone Home Manager configuration should prefer the key `"<username>@<slug>"`.
+- Host-local helper module names should be prefixed by the host slug.
+
+## Summary
+
+- Recently normalized: `john-kde`, `omen-nixos`.
+- Hosts that fit the new rules closely: `janus`, `john-kde`, `omen-nixos`, `test-nix`.
+- Hosts with notable discrepancies: `john-p14s`, `soteria`.
+- Approved exception: `john-pc` directory uses immutable deployed slug `john-pc-ubuntu` for exported keys.
+
+## Detailed Discrepancies
+
+### `john-p14s`
+
+- The main host export uses the canonical slug: `flake.nixosConfigurations.john-p14s`.
+- The host-local helper modules are named `p14sConfiguration` and `p14sHardware`, which drop the `john-` prefix and therefore do not use the full host slug.
+- `networking.hostname` uses the correct host value, but the option name differs from the dominant `networking.hostName` spelling used elsewhere in this tree.
+
+### `john-pc`
+
+- Approved exception for immutable deployed hostname:
+- Directory slug is `john-pc`, but exported keys and hostname bindings intentionally use `john-pc-ubuntu`.
+- `hostname` binding, `flake.modules.homeManager.<name>`, and `flake.homeConfigurations` are aligned to `john-pc-ubuntu`.
+- Shared SSH alias intentionally remains `john-pc-ubuntu` in `modules/services/ssh.nix`.
+
+### `omen-nixos`
+
+- No active discrepancy after normalization:
+- The directory slug, `flake.nixosConfigurations` key, host-local module keys, and `networking.hostName` are now aligned to `omen-nixos`.
+
+### `john-kde`
+
+- No active discrepancy after normalization:
+- The directory slug, `hostname` binding, host-local Home Manager module key, and standalone Home Manager key are now aligned to `john-kde`.
+
+### `soteria`
+
+- Naming is mostly coherent across directory slug, `hostname`, `flake.nixosConfigurations.soteria`, and `flake.modules.homeManager.soteria`.
+- The standalone Home Manager export is `flake.homeConfigurations.soteria`, which does not follow the preferred `"<username>@<slug>"` form.
+- The main host entrypoint is `soteria.nix` instead of the preferred `default.nix`.
+
+## No Discrepancy Found
+
+### `janus`
+
+- Directory slug, `hostname`, `flake.nixosConfigurations.janus`, and `networking.hostName` are aligned.
+- The host-local helper module `janus-ca` is clearly prefixed by the host slug.
+
+### `test-nix`
+
+- The single-file host uses the same slug for the file stem, `hostname`, and `flake.nixosConfigurations.test-nix`.
+- It does not define `networking.hostName`, but it does not contradict the slug anywhere else.
+
+## Follow-up Candidates
+
+- Rename `john-p14s` helper module keys to include the full host slug (`john-p14s-*`) if strict slug consistency is desired.
+- Decide whether `soteria` should move to `default.nix` and whether its standalone Home Manager key should include `john@`.
+- If `john-pc-ubuntu` ever becomes changeable, decide whether to rename the directory to match or keep this as a permanent exception.

.github/instructions/hosts.instructions.md

@@ -37,6 +37,26 @@ Naming in this tree is not perfectly uniform, so preserve existing interfaces un
 - Some hosts export from `default.nix`, while others keep the main definition in a differently named file such as `soteria.nix`.
 - Do not normalize names or move files just for consistency unless the user asks for that structural change.
 
+Naming rules for new hosts:
+
+- Treat the host directory name as the canonical host slug for new work.
+- Prefer `modules/hosts/<slug>/default.nix` as the main entrypoint for a host directory.
+- Use the same slug for the primary `hostname` binding, `flake.nixosConfigurations.<slug>`, and `networking.hostName` unless the task explicitly requires a different deployed hostname.
+- If the host exports a host-local Home Manager module, name it `flake.modules.homeManager.<slug>`.
+- For standalone Home Manager configurations, prefer `flake.homeConfigurations."<username>@<slug>"` so the exported key still carries the host slug.
+- Name host-local helper modules with the same slug as a prefix, for example `flake.modules.nixos.<slug>-hardware` or `flake.modules.nixos.<slug>-configuration`, to make ownership obvious and avoid collisions with shared modules.
+- Keep host-local secrets and auxiliary files under the same host slug directory. Do not point a new host at another host's path just because the contents are similar.
+
+Allowed exception for immutable deployed hostnames:
+
+- If the deployed hostname is externally constrained and cannot change, use that deployed hostname as the canonical slug for exported keys and `hostname` bindings, even if the directory name differs.
+- In that case, keep the exception explicit in comments or reports so future cleanup work does not accidentally rename a live hostname contract.
+
+When working in existing hosts that predate these rules:
+
+- Preserve the current public names by default.
+- If the user asks for a rename or cleanup, update the directory slug, exported flake keys, host-local module names, and `networking.hostName` together in one change so the host identity stays coherent.
+
 Use nearby hosts as composition examples:
 
 - `john-p14s` splits the reusable machine logic into `configuration.nix` and `hardware.nix`, exports `flake.modules.nixos.p14sConfiguration` and `flake.modules.nixos.p14sHardware`, and assembles them from `default.nix`.

.github/instructions/shared-modules.instructions.md

@@ -0,0 +1,54 @@
+---
+description: "Use when defining or modifying reusable Nix modules outside modules/hosts. Covers flake.modules.nixos, flake.modules.homeManager, and flake.factory.user exports, and explains how shared modules differ from concrete host wiring."
+applyTo: 'modules/nixos/**/*.nix, modules/users/**/*.nix, modules/features/**/*.nix, modules/programs/**/*.nix, modules/services/**/*.nix, modules/nix-tools/**/*.nix'
+---
+
+# Shared Modules
+
+Files outside `modules/hosts` generally define reusable building blocks, not concrete machines. In this repo, those files usually export one of these surfaces:
+
+- `flake.modules.nixos.<name>` for reusable NixOS modules.
+- `flake.modules.homeManager.<name>` for reusable Home Manager modules.
+- `config.flake.factory.user` for factories that generate per-user module sets.
+- `flake.meta.*` when the file owns reusable metadata that other modules consume.
+
+Keep the boundary between shared modules and hosts clear:
+
+- Shared modules should not define `flake.nixosConfigurations.<name>` or `flake.homeConfigurations.<name>`; those belong in `modules/hosts`.
+- Prefer generic options, imports, and composition over host-specific literals.
+- If a setting only makes sense for one machine, keep it in that host directory instead of moving it into a shared module.
+- When a host imports a shared module, treat the shared module as part of the stable interface that multiple hosts may depend on.
+
+Follow the existing export patterns in this repo:
+
+- Simple reusable modules may export a single module directly, such as `flake.modules.nixos.games`.
+- Cross-cutting features often live under `modules/features` even when they export `flake.modules.nixos.*` or `flake.modules.homeManager.*`.
+- Program and service integrations commonly export one or both module types from a single file.
+- User definitions under `modules/users` may export metadata plus paired NixOS and Home Manager modules for the same user.
+
+For user modules specifically:
+
+- Keep reusable user facts under `flake.meta.users.<name>` when other modules need to reference them.
+- Prefer deriving the NixOS side from `self.factory.user` when the file already follows that pattern.
+- Keep the user-facing Home Manager module in `flake.modules.homeManager.<name>` and let the factory or host wire it into a concrete configuration.
+- Put user-specific authorized keys, identity, and shared defaults here rather than duplicating them across hosts.
+
+Design shared modules as composable interfaces:
+
+- Import other shared modules instead of copying option blocks.
+- Add options or parameters when behavior needs to vary between hosts.
+- Avoid embedding host-specific paths, hostnames, addresses, or secret file locations unless the file is intentionally host-local.
+- Preserve exported attribute names even when the filename is different. In this repo, the path is not always the public API name.
+
+Use nearby files as examples:
+
+- `modules/nixos/games.nix` is a minimal shared NixOS module with no host wiring.
+- `modules/features/nixos-base.nix` defines a reusable base system module that other hosts import.
+- `modules/users/john.nix` combines `flake.meta.users.john`, a reusable NixOS user module, and a reusable Home Manager user module built around the user factory.
+- `modules/nix-tools/user.nix` defines the `flake.factory.user` helper that shared user modules build on.
+
+For reviews and answers, separate these concerns clearly:
+
+- reusable module API and option design in shared module directories
+- concrete host assembly in `modules/hosts`
+- whether a change increases reuse or accidentally pulls machine-specific behavior into a shared layer