# 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: `michaotic` (planned: `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)
│   ├── git.nix                  # git config
│   ├── ssh.nix                  # SSH matchBlocks
│   ├── zsh.nix                  # shell + aliases
│   ├── kitty.nix                # terminal
│   ├── duti.nix                 # default apps
│   ├── pass.nix                 # pass + gpg-agent (только для GPG)
│   ├── syncthing.nix            # p2p sync
│   ├── zoxide.nix
│   ├── bat.nix
│   ├── eza.nix
│   └── fzf.nix
│
└── 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

```bash
# 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
- не спеши, показывай план, спрашивай подтверждения