From 2078d6bccd1f1fa7a2633ac580a72f527ea38c12 Mon Sep 17 00:00:00 2001 From: m3ta-chiron Date: Sat, 2 May 2026 10:54:42 +0200 Subject: [PATCH] docs: update AGENTS.md for m3ta-home integration, work identity, new structure --- AGENTS.md | 132 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 97 insertions(+), 35 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8e3b0bc..121c2a9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -186,6 +186,8 @@ _(Note to Pi: Your file write/edit tools run in a different directory by default | ---------------- | --------------------------------- | | **Nixpkgs** | nixos-unstable + 25.05 stable | | **Home Manager** | github:nix-community/home-manager | +| **m3ta-home** | code.m3ta.dev/m3tam3re/m3ta-home | +| **m3ta-nixpkgs** | code.m3ta.dev/m3tam3re/nixpkgs | | **Agenix** | github:ryantm/agenix | | **Disko** | github:nix-community/disko | | **NUR** | github:nix-community/NUR | @@ -201,32 +203,33 @@ _(Note to Pi: Your file write/edit tools run in a different directory by default ``` nixos-config/ -├── flake.nix # Entry point: hosts, overlays, dev shells +├── flake.nix # Entry point: hosts, overlays, dev shells, m3ta-home input ├── coding-rules.json # Opencode rules configuration │ ├── hosts/ # Per-host NixOS configurations │ ├── common/ # Shared across all hosts -│ │ ├── users/ # User definitions -│ │ ├── ports.nix # Network ports config -│ │ └── extraServices/ # Common service toggles -│ ├── m3-ares/ # Main desktop -│ ├── m3-atlas/ # Desktop with disko -│ ├── m3-helios/ # Desktop with disko -│ ├── m3-hermes/ # Desktop with disko + hermes-agent -│ └── m3-kratos/ # Server with NUR +│ │ ├── users/ +│ │ │ └── m3tam3re.nix # ← Central user + m3ta-home integration +│ │ ├── default.nix # Shared NixOS settings, overlays, home-manager setup +│ │ ├── ports.nix # Network ports config +│ │ └── extraServices/ # Common service toggles +│ ├── m3-ares/ # TUXEDO laptop (desktop) +│ │ └── home.nix # Hyprland: eDP-1 + HDMI, XDG/MIME +│ ├── m3-kratos/ # AMD desktop (desktop) +│ │ └── home.nix # Hyprland: dual DP, XDG/MIME +│ ├── m3-daedalus/ # Portable laptop (desktop, no Hyprland) +│ │ └── home.nix # XDG/MIME only +│ ├── m3-atlas/ # Primary server (server + coding) +│ ├── m3-helios/ # AdGuard DNS server (minimal server) +│ ├── m3-hermes/ # Secondary server (minimal server) +│ └── m3-aether/ # Cloud VM (minimal server) │ -├── modules/ # Reusable NixOS/home-manager modules -│ ├── nixos/ # NixOS-specific modules -│ │ └── default.nix # Imports common + service configs -│ └── home-manager/ # Home-manager configurations +├── modules/ # Reusable NixOS modules +│ └── nixos/ # NixOS-specific modules │ -├── home/ # Per-user, per-host home configs -│ └── m3tam3re/ -│ └── m3-daedalus.nix -│ -├── overlays/ # Package overlays -│ ├── default.nix # Stable/locked/master branches -│ └── mods/ # Package modifications +├── overlays/ # Package overlays (stable/locked/master/pinned) +│ ├── default.nix +│ └── mods/ │ ├── pkgs/ # Custom packages │ @@ -234,13 +237,64 @@ nixos-config/ │ └── secrets.nix │ ├── .opencode-rules/ # Opencode AI rules -│ ├── concerns/ # Coding style rules -│ ├── languages/nix.md # Nix conventions +│ ├── concerns/ +│ ├── languages/nix.md │ └── USAGE.md │ └── .pi/ # Agent configuration ``` +### Home-Manager Integration + +Home-Manager configs are managed centrally in the **`m3ta-home`** repository: +- **Repo**: `code.m3ta.dev/m3tam3re/m3ta-home` +- **Docs**: See m3ta-home README for full documentation + +What lives where: + +| Concern | Location | Why | +|---------|----------|-----| +| Shell, CLI tools, editors, apps | `m3ta-home/profiles/` | Portable across all hosts | +| User identity (git, SSH, JJ) | `m3ta-home/users/` | Switchable: private vs work | +| Feature flags (enable/disable) | `nixos-config/hosts/common/users/m3tam3re.nix` | Per-host decisions | +| Monitor layouts, window rules | `nixos-config/hosts//home.nix` | Hardware-specific | +| XDG/MIME defaults | `nixos-config/hosts//home.nix` | Host-specific preferences | +| NixOS overlays | `nixos-config/overlays/` | System-level package management | + +#### Host → Profile Mapping + +Defined in `hosts/common/users/m3tam3re.nix`: + +```nix +hostProfiles = { + # Desktop hosts + m3-ares = { context = "desktop"; sets = ["coding" "gaming" "media"]; }; + m3-kratos = { context = "desktop"; sets = ["coding" "gaming" "media"]; }; + m3-daedalus = { context = "desktop"; sets = ["coding" "media"]; }; + # Server hosts + m3-atlas = { context = "server"; sets = ["coding"]; }; + m3-helios = { context = "server"; sets = []; }; + m3-hermes = { context = "server"; sets = []; }; + m3-aether = { context = "server"; sets = []; }; +}; +``` + +#### Work Identity Use Case + +The same `m3ta-home` repo supports a **work identity** for company machines: + +```nix +# On a work NixOS machine: +(m3ta-lib.mkHome { + user = "m3tam3re"; + identity = "work"; # ← switches git to sascha.koenig, SSH to AZ hosts + context = "desktop"; + sets = ["coding"]; +}) +``` + +This provides the familiar shell/editor/CLI setup but with work git credentials and SSH configuration. + --- ## Commands @@ -311,6 +365,14 @@ config = lib.mkMerge [ - Never commit plaintext secrets - Use `.nix` extension for secret files +### Flake Input URLs + +All `code.m3ta.dev` inputs use **SSH** URLs: +```nix +url = "git+ssh://gitea@code.m3ta.dev/m3tam3re/"; +``` +Anonymous HTTPS git on Gitea is unreliable and prompts for auth. SSH works with configured keys. + --- ## Key Files @@ -318,12 +380,9 @@ config = lib.mkMerge [ | File | Purpose | | ---------------------------------- | ------------------------------------------------------------------------------------------ | | `flake.nix` | Central entry point defining all hosts, overlays, packages, dev shells, and nixpkgs config | -| `hosts/common/default.nix` | Shared Nix settings, nixpkgs overlays, home-manager integration, user defaults | -| `hosts/m3-ares/default.nix` | Main desktop host configuration, imports common + service modules | -| `hosts/m3-ares/configuration.nix` | Desktop environment config (Hyprland, display, audio, etc.) | -| `hosts/m3-ares/programs.nix` | CLI tools, dev tools, shell configs | -| `hosts/m3-ares/services/` | Service-specific configs (firewall, printing, etc.) | -| `modules/nixos/default.nix` | Orchestrates common + configuration imports | +| `hosts/common/default.nix` | Shared Nix settings, nixpkgs overlays, home-manager setup (`useGlobalPkgs = true`) | +| `hosts/common/users/m3tam3re.nix` | User definition + m3ta-home mkHome integration + per-host feature flags | +| `hosts//home.nix` | Host-specific overrides: monitors, workspaces, window rules, XDG/MIME | | `overlays/default.nix` | Package version overrides (stable/locked/master branches) | | `.opencode-rules/languages/nix.md` | Nix-specific conventions and patterns | @@ -352,7 +411,10 @@ config = lib.mkMerge [ - `configuration.nix` — host-specific system config - `hardware-configuration.nix` — from `nixos-generate-config` - `programs.nix`, `services/`, `secrets.nix` as needed -3. Run `sudo nixos-generate-config --dir ./hosts/new-host` first time +3. Add entry to `hostProfiles` in `hosts/common/users/m3tam3re.nix` +4. Add feature flags in the `hostFlags` section +5. Create `hosts//home.nix` if the host needs monitor/XDG overrides +6. Run `sudo nixos-generate-config --dir ./hosts/new-host` first time ### Adding a New Package @@ -360,6 +422,12 @@ config = lib.mkMerge [ 2. For complex packages: create in `pkgs/` directory 3. For upstream packages: use NUR or add as flake input +### Adding a New Home-Manager Feature + +1. Create the module in `m3ta-home` under the appropriate profile directory +2. Add the import to the parent `default.nix` in m3ta-home +3. Enable it per-host via feature flags in `hosts/common/users/m3tam3re.nix` + ### Development Workflow 1. Edit config files @@ -375,9 +443,3 @@ config = lib.mkMerge [ nix copy --to ssh://user@host .#nixosConfigurations.m3-ares.config.system.build.toplevel ssh user@host 'sudo nixos-rebuild switch --flake /nix/store/...-closure' ``` - -### Home Manager - -- Home configs live in `home/m3tam3re/` -- Use `home-manager.users.m3tam3re` in host config -- Access via `config.home-manager.users.m3tam3re`