# Каталог пакетов руководящей документации

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

Раздел описывает каталог пакетов руководящей документации для агентов. Такие пакеты живут в отдельных репозиториях и попадают в рабочий контур агента как локально доступный источник.

Проектная документация конкретного продукта не становится пакетом руководящей документации только потому, что агенту нужно её читать.

## Базовая модель

| Объект | Назначение |
|---|---|
| Руководящий пакет | Каталоговая запись пакета с видом `guidance`. |
| Версия руководящего пакета | Конкретная версия руководящих документов, шаблонов или правил. |
| Установка руководящего пакета | Установка версии в области платформы, организации, проекта или репозитория. |
| Источник руководящего пакета | Репозиторий-источник и зафиксированный `tag`, `commit` или gitlink. |

`package-hub` хранит пакет, версию, установку и manifest. Сами документы остаются в репозитории-источнике и попадают в рабочий контур как локальный источник.

## Чтения из package-hub

`package-hub` не вводит отдельные сущности и ручки только для руководящих пакетов. Руководящий пакет является обычной пакетной записью с видом `guidance`, поэтому будущие потребители используют существующие чтения:

| Нужно получить | Как читать |
|---|---|
| Доступные руководящие пакеты | `ListPackages` с фильтром `package_kind=guidance`. |
| Установленные руководящие пакеты в scope | `ListPackageInstallations` с фильтром `package_kind=guidance` и нужной областью установки. |
| Проверенный manifest версии | `GetPackageManifest` по выбранной версии пакета. |

Эти чтения дают идентификаторы пакета, выбранную версию, manifest и статус установки. Checkout репозитория, mount документов в workspace и порядок применения руководств выполняют `agent-manager` и runtime-контур по проектной политике.

## Первые репозитории-источники

- `github.com/codex-k8s/kodex-guidelines-common-ru` — общие инженерные правила, source submodule `docs/external/guidelines/common`.
- `github.com/codex-k8s/kodex-guidelines-go-backend-ru` — правила для Go backend, source submodule `docs/external/guidelines/go`.
- `github.com/codex-k8s/kodex-guidelines-vue-frontend-ru` — правила для Vue и TypeScript frontend, source submodule `docs/external/guidelines/vue`.

`docs/design-guidelines/**` содержит проектный overlay поверх подключённых руководящих пакетов. Универсальные изменения вносятся в соответствующий внешний репозиторий, затем в `kodex` обновляется gitlink.

Шаблоны документации вынесены отдельно и не считаются пакетом руководящей документации: публичный источник шаблонов — `github.com/codex-k8s/kodex-doc-templates-ru`, source submodule — `docs/templates`.

## Именование

- Пакет руководящей документации не должен называться по конкретному проекту-потребителю.
- Каноническая схема имени: `kodex-guidelines-<subject>-<locale>`.
- `<subject>` должен описывать предметную область пакета, например `common`, `go-backend` или `vue-frontend`.
- `<locale>` обязателен и ставится в конце slug. Примеры: `ru`, `en`.

## Границы

- Руководящий пакет не заменяет проектную документацию.
- Проектные документы и документы сервисов описываются в проектной политике и источниках документации проекта.
- Self-improve задача по руководящему пакету работает с репозиторием этого пакета как с целевым рабочим репозиторием.
- Текст руководящих документов не хранится в БД `package-hub`; БД хранит метаданные, версию, manifest, статус и установку.
- Manifest руководящего пакета обязан указать вид `guidance` и capability `guidance`.
- Manifest руководящего пакета не должен указывать capability `store` или `platform_content`.
- Руководящий пакет не должен требовать runtime-нагрузку, секреты, действия доступа или API платформы: подключение документов в workspace выполняют соседние домены по локальной политике проекта.
- Если руководящему пакету нужны исполняемые действия, внешние токены или API платформы, это уже не чистый `guidance`, а отдельный пакет плагина или иной специализированный вид пакета.
