nix-config/AGENTS.md

AGENTS.md

для AI агентов, работающих с этим репозиторием

what is this

• declarative nix config для нескольких хостов через nix-darwin + home-manager
• активный: poppy (MacBook Air M1)
• planned: muscari (NixOS server), rosemary (backup VM)
• user: mikl

structure

~/repos/nix-config/
├── flake.nix                    # entry point
├── flake.lock                   # locked deps
├── AGENTS.md                    # этот файл
├── garden.md                    # future plans, TODO, миграции
│
├── hosts/
│   ├── poppy/                   # macbook (active daily driver)
│   │   ├── default.nix          # основной конфиг
│   │   ├── apps.nix             # brew casks + nix GUI пакеты
│   │   └── system.nix           # macOS defaults
│   ├── muscari/                 # NixOS server (planned)
│   └── common/                  # shared NixOS config
│
├── home/                        # home-manager modules
│   ├── default.nix              # imports, sessionVariables
│   ├── cli.nix                  # CLI tools (universal) + zoxide, bat, eza, fzf
│   ├── git.nix                  # git config
│   ├── ssh.nix                  # SSH matchBlocks
│   ├── zsh.nix                  # shell + aliases
│   ├── kitty.nix                # terminal
│   ├── duti.nix                 # default apps (macOS only)
│   ├── pass.nix                 # pass + gpg-agent (только для GPG)
│   └── syncthing.nix            # p2p sync
│
└── docs/                        # документация
    ├── structure.md             # high-level overview
    ├── poppy.md                 # macbook specifics
    ├── muscari.md               # server + k3s
    ├── shell.md                 # zsh + pure
    ├── terminal.md              # kitty
    ├── ssh.md                   # SSH keys, FIDO2, recovery
    ├── apps.md                  # список приложений
    ├── cheatsheet.md            # quick commands
    └── bootstrap.md             # manual setup guide

commands

# rebuild poppy
sudo darwin-rebuild switch --flake .#poppy

# rebuild muscari
sudo nixos-rebuild switch --flake .#muscari

# validate before applying
nix flake check

# update dependencies
nix flake update

# cleanup old generations
nix-collect-garbage -d

важные правила

при работе с файлами

• сначала показывай план, потом делай
• никогда не удаляй user data (GPG, SSH ключи, pass-store)
• новые файлы в home/ обсуждай перед созданием
• длинные изменения дроби на отдельные коммиты

пакеты

• CLI tools → home/cli.nix (universal)
• GUI apps через nix → hosts/poppy/apps.nix (use environment.systemPackages, NOT home.packages)
• brew casks → hosts/poppy/apps.nix (тот же файл)
• App Store apps → ручная установка, в docs/apps.md
• homebrew.onActivation.cleanup = "none" (по умолчанию, безопаснее)
  • "zap" удалит всё что не в nix config

SSH ключи

• home/ssh.nix — matchBlocks для forgejo/github/sol.moe
• не добавляй credential.helper (мы ходим по SSH, не HTTPS)
• FIDO2 ключи (Ledger) — нужен nixpkgs#libfido2 и nixpkgs#openssh через nix shell
• подробности в docs/ssh.md

git workflow

• основной remote: forgejo (ssh://git@git.iscg.dev:2222/mikl/nix-config.git)
• перед каждым значимым изменением спрашивай подтверждение
• не делай git push --force без явного подтверждения

backup и recovery

• GPG ключ → https://git.iscg.dev/mikl/gpg (private)
• pass-store → https://git.iscg.dev/mikl/pass (синхронизирован)
• nix-config → https://git.iscg.dev/mikl/nix-config
• Obsidian traces → https://git.iscg.dev/mikl/traces + Syncthing
• Time Machine → основной бэкап всего

что в работе (TODO)

• sops-nix для OPENROUTER_API_KEY
• rosemary setup (NixOS VM)
• FIDO2 в nix-config постоянно (libfido2, openssh)
• pass-store remotes (github, git.sol.moe)
• pre-commit с alejandra
• uncomment aseprite в hosts/poppy/apps.nix (10-30 мин компиляции)

новые хосты

при добавлении нового хоста:

1. создать hosts/<name>/{default,system}.nix
2. добавить в flake.nix mkNixos или mkDarwin
3. создать docs/<name>.md с описанием
4. обновить garden.md

контекст для пользователя

• студент, hse university
• интересы: LLM/AI, it infra, self-hosted, литература
• ADHD, прокрастинация — не отвлекай на ненужные темы
• общается на русском и английском
• использует Telegram MCP, Forgejo MCP, SearXNG
• конфиг для macOS, учится nix
• не спеши, показывай план, спрашивай подтверждения