# Каталоги платформы

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

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

## Разделы

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

## Правило выноса

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

## Правило именования

- Пакеты руководящей документации именуются по схеме `kodex-guidelines-<subject>-<locale>`.
- Шаблоны документации именуются по схеме `kodex-doc-templates-<locale>`.
- Для документационных пакетов суффикс локали в конце slug обязателен. Примеры: `-ru`, `-en`.
- Platform-owned package repos именуются по схеме `kodex-package-<name>`.

## Виды пакетов

Пакетный manifest обязан явно указать один из видов пакета. Вид задаёт границу ответственности, а capability внутри manifest уточняет конкретную возможность.

| Вид | Каталог | Главное правило |
|---|---|---|
| `plugin` | `plugins/` | Исполняемое расширение платформы; может требовать runtime, секреты и действия доступа. |
| `guidance` | `guidance-packages/` | Руководящие документы и правила; не требует runtime, секреты, действия доступа или API платформы. |
| `store` | `package-store/` | Магазин пакетов как устанавливаемый пакет и источник доступного каталога. |
| `platform_content` | `package-store/` | Сайт, справка, API-документация и пользовательские материалы платформы; не является руководящим пакетом для агентов. |

Зарезервированные capability `guidance`, `store` и `platform_content` не смешиваются между видами пакетов. Если пакету нужна новая смешанная модель поведения, сначала проектируется новый вид или отдельное расширение manifest, а не добавляется чужая capability в существующий вид.

Сами файлы руководств, сайта, справки, API-материалов и внешнего каталога магазина не хранятся в БД `package-hub`. БД хранит локальную пакетную истину: источник, пакет, версию, manifest, установку, проверку и статусы.
