diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..fd7ad0d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,135 @@
+# 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
+- не спеши, показывай план, спрашивай подтверждения