docs: update AGENTS.md for m3ta-home integration, work identity, new structure
This commit is contained in:
132
AGENTS.md
132
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/<name>/home.nix` | Hardware-specific |
|
||||
| XDG/MIME defaults | `nixos-config/hosts/<name>/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/<repo>";
|
||||
```
|
||||
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/<name>/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/<name>/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`
|
||||
|
||||
Reference in New Issue
Block a user