Save this content to: AGENTS.md

# MagicPro package

**MagicPro** is a CMS that combines the speed of a CMS with the flexibility of Laravel 13.
Controllers, Blade views, routes, pages, menus and settings are managed through a single
database structure (Articles) and an admin panel instead of scattered files.

This file only says where to read. Nothing is imported here: the documentation changes on
its own, this file stays.

**Read before touching the code**

**Читать перед любой правкой кода. Это приказы, а не пожелания.**

## Порядок работы

- Вопрос — это не задача. Спросили — ответь и остановись. Ничего не делать значит
  вообще ничего: ни правок, ни чтения файлов, ни поиска по коду, ни команд, ни
  проверок в браузере — даже ради более точного ответа. Не хватает данных — так и
  скажи и жди. Действовать можно только по прямому указанию.
- Задача понятна — выполни ровно её, без дополнительных улучшений.
- Задача неоднозначна, не хватает данных или её можно понять двояко — задай вопрос.
  Не угадывай и не придумывай недостающее.
- Считаешь, что нужна дополнительная работа, — сначала спроси, потом делай.
- Одна задача — одно действие. Один тест значит один тест, одна функция — только
  эта функция.
- Не добавляй подготовку, которой не просили: создание данных, вызовы соседних
  команд, лишние тесты и хелперы.
- Перед правкой коротко скажи, что изменишь. После правки перечисли изменённые файлы
  и объясни, что в них поменялось.
- Отвечай по-русски. Код, комментарии и сообщения коммитов пиши по-английски, как в
  существующем коде.

## Чтение и поиск информации

- Без дополнительного разрешения читай любые файлы внутри проекта, просматривай каталоги, ищи по всему репозиторию и автоматически переходи по ссылкам и упоминаниям в другие файлы.
- Для сбора и анализа информации запускай любые команды Linux в режиме только чтения, в том числе `pwd`, `ls`, `find`, `fd`, `tree`, `rg`, `grep`, `sed`, `awk`, `cut`, `tr`, `head`, `tail`, `sort`, `uniq`, `wc`, `file`, `stat`, `readlink`, `realpath`, `diff`, `cmp`, `jq`, `yq`, `sha256sum`, `tar -tf` и `unzip -l`, а также их безопасные эквиваленты. Можно просматривать структуру, метаданные, типы и содержимое файлов, разрешать пути, фильтровать, извлекать, сортировать, сравнивать и подсчитывать данные. Эти действия не должны менять файлы или их метаданные, обращаться к базе данных и внешним сервисам, запускать код приложения либо обходить отдельные запреты на Git, Composer и другие операции ниже.

## Чтение файлов при выполнении задачи

Для выполнения прямо поставленной задачи можно без дополнительного разрешения
читать любые файлы и каталоги проекта, искать по коду, изучать конфиги, исходники,
документацию и логи. Не ограничивайся файлами, явно названными в задаче: читай все
связанные файлы, необходимые для понимания контекста.

Это разрешение действует только при выполнении задачи. Если пользователь задал
вопрос, действует правило «Вопрос — это не задача».

## Без разрешения не делать

- Не работать с базой данных: никаких записей, миграций и `artisan migrate`.
- Не трогать Composer: ни `composer.json`, ни `composer.lock`, ни команды
  `install`, `update` и `dump-autoload`. Если нужна правка автозагрузки — сообщить
  об этом и ждать решения.
- Не удалять файлы.
- Не делать коммиты и вообще не выполнять действия в Git.
- Не трогать `vendor/dixipro/magicpro` — это симлинк на пакет.
- Не редактировать сгенерированные файлы в `storage/dataMagicPro/`: они будут
  перезаписаны.
- Не менять соседний проект `/home/m/mpro3.test`. Читать его можно.
- Не запускать код приложения для проверки своей правки. Если проверка нужна —
  сообщить об этом или проверить через браузер.

## Где работать

Продукт находится в `packages/dixipro/magicpro`. Корневое Laravel-приложение —
только хост; пакет подключён через Composer-симлинк.

Не искать логику продукта в корневом `app/` и не менять корневой boilerplate,
если об этом прямо не попросили.

Использовать только Laravel 13, его синтаксис и возможности.

## Проверки

- Изменённые PHP-файлы проверять командой `php -l`. Только синтаксис; стилевые
  фиксаторы не запускать.
- Фронтенд админки собирается из каталога пакета:
  `cd packages/dixipro/magicpro && npm run build`.
- Файлы `* copy.php` и `* copy.js` — устаревшие резервные копии. Не менять их и не
  использовать как образец.

## Документация

- Описана в файле docs\ru\index.json
- Читай ее
- Поле "agent": true относится к MCP агенту

Порядок и имена разделов задаёт [`docs/ru/index.json`](../index.json). Обход папок
не определяет ни порядок, ни человеческие названия. Новый файл нужно добавить в
индекс, иначе он не появится в разделе документации админки.

Запись или группа в индексе с `"agent": true` доступна MCP-агенту через
`list-docs`. Без этой пометки страница остаётся только в админке. Для каждой новой
страницы нужно заполнить `about` — краткое описание, по которому агент выбирает,
что читать.

## MCP

У проекта есть собственный MCP-сервер `magicpro`. Задачу, которую можно выполнить
его инструментом, выполнять инструментом, а не ручной правкой файлов.

- Документацичя docs\ru\index.json ->"name": "МСП"

## Ленты

- Не писать напрямую SQL в `magicPro_feed_items`: в обход модели не рассчитывается
  `__position`, не проверяются ссылки и не удаляются файлы.
- Записи создавать через ленту (`$feed->items()->create()`), а не через
  `FeedItem::create()`: без ленты новая запись не знает своей схемы.
- Искать и сортировать можно только по слотам. Поля из `__data` для этого не
  подходят: у них нет отдельных колонок.
- Запись, на которую ссылаются, нельзя удалить. Кольца связей запрещены.
- Новый слот требует новой миграции, константы в `FeedItem` и индексов. Старую
  миграцию не менять.
- Любое изменение схемы проводить через сохранение ленты, иначе не увеличится
  `schemaGeneration` и разойдутся устаревшие карты.

### Структура файлов

Для каждого модуля используется отдельная папка по названии системы, примеры

```text
docs/ru/mainUse/   сборка сайта: статьи, маршруты, вёрстка
docs/ru/mainDev/   разработка пакета: ядро, установка, поиск ошибок
docs/ru/feed/      ленты
docs/ru/image/     ресайзер
docs/ru/mail/      почтовая система
docs/ru/mcp/       MCP-сервер
docs/ru/helpers/   MproHelper
```

## Задачи и находки

`toDo/` в корне пакета — что предстоит сделать, черновики ТЗ и заметки. Документация — это
то, что уже сделано, а не то, что задумано, поэтому в `docs/` черновиков нет.