stt, mem0, rofi-project-opener

hosts/common/AGENTS.md

@@ -0,0 +1,76 @@
+# COMMON HOST CONFIGURATION
+
+**Shared base configuration and abstractions for all hosts**
+
+## OVERVIEW
+Common imports, overlays, and custom patterns (extraServices, ports) used across 6 hosts.
+
+## STRUCTURE
+```
+common/
+├── default.nix          # Base imports, overlays, nix settings
+├── ports.nix            # Centralized port registry
+├── extraServices/       # Optional service modules
+│   ├── default.nix
+│   ├── flatpak.nix
+│   ├── ollama.nix
+│   ├── podman.nix
+│   └── virtualisation.nix
+└── users/
+    ├── default.nix
+    └── m3tam3re.nix     # Primary user definition
+```
+
+## WHERE TO LOOK
+
+| Task | Location | Notes |
+|------|----------|-------|
+| Add port definition | ports.nix | Use config.m3ta.ports.get |
+| Enable optional service | Host config extraServices | Boolean flags |
+| Modify overlays | default.nix lines 27-36 | 5 overlay sources |
+| Add new user | users/ | Shared across all hosts |
+
+## CONVENTIONS
+
+### Port Registry Pattern
+```nix
+# Define in ports.nix
+definitions = {
+  myservice = 3099;
+};
+
+# Access in host config
+config.m3ta.ports.get "myservice"  # Returns 3099
+```
+
+### extraServices Abstraction
+Host configs enable via boolean:
+```nix
+extraServices = {
+  podman.enable = true;      # Container runtime
+  ollama.enable = true;      # LLM inference
+  flatpak.enable = false;    # Flatpak apps
+  virtualisation.enable = true;  # QEMU/KVM
+};
+```
+
+### Overlay Precedence (bottom overrides top)
+1. stable-packages (nixpkgs-stable)
+2. locked-packages (nixpkgs-locked)
+3. pinned-packages (nixpkgs-45570c2, nixpkgs-9e58ed7)
+4. master-packages (nixpkgs-master)
+5. m3ta-nixpkgs (local custom overlay)
+
+## ANTI-PATTERNS
+
+- **DON'T** add host-specific logic to common/ - belongs in hosts/<name>/
+- **DON'T** bypass port registry - hardcoded ports break consistency
+- **DON'T** modify user shell globally - set per-user if needed
+
+## NOTES
+
+- Nix GC runs weekly, keeps 30 days
+- Trusted users: root, m3tam3re
+- Default shell: Nushell (set line 77)
+- Home-manager integrated at common level, not per-host
+- TODO on line 69: ports should only return actually used ports