# Инструкции для агентов в `docs/catalogs/**`

## Назначение

`docs/catalogs/**` описывает каталоги платформы: пакеты, плагины, пакеты руководящей документации, роли агентов, процессы `flow` и шаблоны промптов.

## Перед изменениями

- Читать `docs/AGENTS.md`.
- Читать `docs/catalogs/README.md`.
- Читать `refactoring/task.md` и `refactoring/03-domain-map.md`, если изменение связано с пакетами, магазином пакетов, плагинами или руководящей документацией.
- Читать `docs/external/AGENTS.md`, если изменение затрагивает документационный submodule-источник.
- Читать `packages/AGENTS.md`, если изменение затрагивает пакетный submodule-источник.
- Читать `docs/templates/index.md` и выбирать шаблон под тип создаваемого документа.

## Разделы

- `docs/catalogs/package-store/**` — магазин пакетов как устанавливаемый пакет и источник доступных пакетов.
- `docs/catalogs/plugins/**` — правила публикации, проверки, установки и эксплуатации плагинов.
- `docs/catalogs/guidance-packages/**` — пакеты руководящей документации для агентов.
- `docs/catalogs/prompt-roles/**` — встроенные и пользовательские роли, процессы `flow` и шаблоны промптов.

## Правила содержания

- Магазин пакетов является отдельным пакетом платформы из отдельного приватного репозитория; ядро платформы и `package-platform` работают с ним как с внешним источником данных и установок.
- Авторский магазин пакетов расположен в `github.com/codex-k8s/kodex-package-store` и подключён как пакет `packages/package-store`.
- Каталог установленных пакетов есть у каждой инсталляции платформы, а каталог доступных пакетов может получать данные из магазина пакетов.
- Пользовательская документация платформы, например API и правила разработки пакетов, поставляется отдельным пакетом сайта и документации из `github.com/codex-k8s/kodex-package-platform-site`, подключённым как пакет `packages/platform-site`.
- Публичный источник шаблонов документации расположен в `github.com/codex-k8s/kodex-doc-templates-ru` и подключён как source submodule `docs/templates`.
- Текст шаблонов промптов, процессов `flow` и руководящих пакетов хранится в репозиториях-источниках, а не как свободный текст в БД.
- Не смешивать проектную продуктовую документацию с руководящими пакетами для агентов.
- Source submodule перечисляются в `.gitmodules`; `services.yaml` хранит политику checkout, а не дублирующий реестр источников.
- Для внешних пакетов руководящих правил использовать схему slug `kodex-guidelines-<subject>-<locale>`.
- Для документационных пакетов суффикс локали в конце slug обязателен. Примеры: `-ru`, `-en`.
- Для platform-owned package repos использовать схему slug `kodex-package-<name>`.
