diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..d94dd68
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,101 @@
+# AGENTS.md — инструкция для агентов
+
+## О проекте
+
+**ocStore (OpenCart) 3.0.3.7** — интернет-магазин на PHP с Twig-шаблонами.
+
+- **Платформа:** ocStore 3.0.3.7 (форк OpenCart)
+- **PHP:** >= 8.5
+- **Шаблонизатор:** Twig 3.0
+- **Язык:** русский (ru-ru)
+- **База данных:** MySQL (драйвер mysqli)
+- **Веб-сервер:** Apache с mod_rewrite
+
+## Структура проекта
+
+```
+public/
+├── admin/          # Админ-панель (MVC)
+│   ├── controller/ # Контроллеры
+│   ├── language/   # Языковые файлы ru-ru
+│   ├── model/      # Модели
+│   ├── view/       # Twig-шаблоны (.twig)
+│   └── index.php
+├── store/          # Витрина / каталог (MVC)
+│   ├── controller/
+│   ├── language/
+│   ├── model/
+│   └── view/theme/ # Тема оформления
+├── system/         # Ядро (фреймворк, библиотеки, хелперы)
+│   ├── engine/     # Роутинг, экшены, загрузчик
+│   ├── library/    # Библиотеки (language, config, template, …)
+│   ├── helper/     # Хелперы
+│   └── config/     # Конфигурация ядра
+├── image/          # Изображения товаров
+├── config.php      # Конфигурация (в .gitignore!)
+└── index.php       # Точка входа
+storage/
+├── cache/          # Кэш (в .gitignore)
+├── logs/           # Логи (в .gitignore)
+├── modification/   # Модификации OCMOD (в .gitignore)
+├── session/        # Сессии PHP (в .gitignore)
+├── upload/         # Загрузки (в .gitignore)
+├── download/       # Файлы для скачивания (в .gitignore)
+└── vendor/         # Composer-зависимости (в .gitignore, Twig)
+```
+
+## Важные правила
+
+### Никогда не коммитить
+- `public/config.php` и `public/admin/config.php` — содержат пароли БД
+- `storage/` целиком (кроме `index.html`)
+- `vendor/` — устанавливается через Composer
+- Файлы кэша, логов, сессий
+- `public/image/` — изображения хранятся отдельно
+
+### Коммиты
+- Сообщения коммитов — **на русском языке**
+- Стиль: кратко, что сделано (пример: `"Блог в меню"`, `"Удалил googleshopping"`)
+
+### Код-стайл
+- PHP: без строгой типизации, используется `$_` суперглобальный массив для языковых переменных
+- Языковые файлы — ассоциативный массив `$_['key'] = 'значение';`
+- Контроллеры — классы в `Controller*` namespace
+- Модели — классы в `Model*` namespace
+- Шаблоны — `.twig` файлы
+- Формат языковых переменных в шаблонах: `{{ text_yes }}`, `{{ button_save }}`
+- Формат языковых констант: `$_['text_yes']`, `$_['button_save']` и т.д.
+
+### OpenCart MVC (паттерн)
+- URL-роутинг: `index.php?route=common/home` загружает `controller/common/home.php`
+- Контроллер вызывает `$this->load->model('catalog/product')` для загрузки модели
+- Контроллер вызывает `$this->load->language('product/product')` для языкового файла
+- Шаблоны рендерятся через `$this->response->setOutput($this->load->view(...))`
+
+### Модификации (OCMOD)
+- OCMOD-модификации лежат в `public/system/modification.xml`
+- Изменённые файлы попадают в `storage/modification/` — не трогать вручную
+
+### Composer
+- Зависимости: Twig 3.0
+- Установка: `composer install` в `storage/`
+
+## Работа с расширениями
+
+Расширения (модули, темы, платёжные шлюзы и т.д.) устанавливаются через админ-панель или вручную:
+- Модули: `public/admin/controller/extension/module/`, `public/store/controller/extension/module/`
+- Темы: `public/store/view/theme/`
+- Языковые файлы расширений: `public/admin/language/ru-ru/extension/`
+
+## Полезные команды
+
+```bash
+# Очистка кэша
+rm -rf storage/cache/*
+
+# Установка зависимостей
+cd storage && composer install
+
+# Просмотр логов
+tail -f storage/logs/error.log
+```