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

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

`docs/external/**` содержит source submodule-ссылки на внешние репозитории руководящей документации. Это не место для редактирования активной каноники `docs/**` напрямую.

Активная документация должна жить в `docs/**` без отдельного параллельного корня. Если нужен внешний репозиторий-источник, он подключается под `docs/external/**`, а не в новую верхнеуровневую папку.

## Правила работы

- Инициализировать все документационные submodule, объявленные в `.gitmodules` для текущего рабочего контура.
- Массовую синхронизацию submodule выполнять только когда задача требует обновить все объявленные источники.
- Если меняется содержимое внешнего репозитория, сначала commit/push делается внутри этого внешнего репозитория, затем в `kodex` обновляется только gitlink.
- Изменения в содержимом внешнего репозитория вносятся через отдельную ветку и PR этого репозитория; обновление gitlink в `kodex` делается уже после merge.
- Если внешний источник закрыт или недоступен текущему пользователю, платформа должна показать отсутствие доступа; агент не должен подменять такой источник локальной копией.
- Внешние пакеты правил должны оставаться переиспользуемыми: не добавлять в них обязательные нормы, привязанные к конкретному проекту, продукту, slug репозитория, префиксу env, схеме входа или частной delivery-политике.
- Проектно-специфичные ограничения и уточнения должны жить в локальной активной документации проекта, а не во внешнем пакете.
- Примеры допускаются, если они явно помечены как примеры и не превращаются в обязательную норму для всех потребителей пакета.
- Если меняется проектный overlay гайдов в `docs/design-guidelines/**`, проверить, нужно ли вынести универсальное правило во внешний пакет в `docs/external/guidelines/**`.
- Шаблоны документации подключаются отдельным source submodule в `docs/templates`.
- Если проекту нужен иной набор шаблонов, использовать отдельный репозиторий шаблонов и привязку через `services.yaml`, а не ручное копирование шаблонов.

## Именование репозиториев

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

## Источники

- Общие гайды: `docs/external/guidelines/common`.
- Go-гайды: `docs/external/guidelines/go`.
- Vue-гайды: `docs/external/guidelines/vue`.

Если внешний источник импортирован в проект, его правила обязательны. Проектное уточнение может переопределять правила проекта-потребителя, но не превращает внешний пакет в ручную копию.
