Docs

# Skill `ocx` в образе opencodex-docker

Этот репозиторий поставляет копию upstream-навыка `skills/ocx` из
`lidge-jun/opencodex` и **отдельное дополнение** `skills/ocx/references/container-hub.md`
для Docker/Kubernetes-развёртывания. Дополнение не входит в upstream и не должно
перезаписываться при синхронизации.

## Использование

- Навык находится в `skills/ocx/` и содержит `SKILL.md` плюс все reference-файлы.
- `SKILL.md` обязательно ссылается на `references/container-hub.md`; этот файл создаётся
  и поддерживается отдельно (расширение container hub).
- Upstream-навык распространяется под MIT (см. upstream `LICENSE`); packaging-репозиторий
  сохраняет эту лицензию.

## Синхронизация с upstream

Синхронизация по умолчанию отслеживает актуальный `main`; для воспроизводимого
запуска ревизию можно закрепить переменной окружения:

```bash
OCX_UPSTREAM_SKILL_REVISION=684ad75d254ae96a9971387d09ae428b96ada9c2 scripts/sync-ocx-skill.sh
```


Команды:

```bash
# Применить обновления upstream, сохранив references/container-hub.md
scripts/sync-ocx-skill.sh

# Только проверка (без изменений), код 0 = синхронизировано
scripts/sync-ocx-skill.sh --check
# или
scripts/check-ocx-skill.sh
```

Можно переопределить ревизию/репозиторий через переменные окружения:
`OCX_UPSTREAM_SKILL_REVISION` (по умолчанию `main`), `OCX_UPSTREAM_REPO_URL`.

## Безопасное обновление

- Перед изменением скрипт читает сохранённую upstream-ревизию из
  `skills/ocx/.upstream-revision` и сравнивает локальные файлы с их базовыми
  upstream-версиями. Если upstream-owned файл менялся локально, отсутствует,
  либо новый upstream-файл конфликтует с локальным путём, синхронизация
  прекращается **до записи**. Такие конфликты требуют ручного разбора.
- При безопасном обновлении скрипт заменяет upstream-owned файлы и удаляет
  только upstream-файлы, удалённые upstream, не затрагивая посторонние локальные
  файлы. `references/container-hub.md` — локальное дополнение, исключённое из
  переноса и удаления.
- `SKILL.md` получает строку-ссылку на дополнение. Если upstream изменил
  ожидаемую строку reference-таблицы и ссылку нельзя вставить безопасно, скрипт
  завершится без изменений.
- `.upstream-revision` обновляется на полный SHA только когда upstream-owned
  содержимое навыка/лицензии действительно изменилось. Новые upstream-коммиты
  без content drift не создают фиктивное обновление stamp/PR. Не меняйте stamp
  вручную: он нужен как безопасная merge-base для локальных изменений.
- Проверка (`--check`) показывает дрейф и различия без записи. Дрейф не должен
  останавливать сборку/публикацию образа; он служит сигналом для отдельного
  безопасного PR обновления навыка.
- Upstream-навык распространяется по MIT. В корневом `LICENSE` сохранены
  требуемые upstream copyright notice и текст MIT License. Копия upstream
  `LICENSE` также хранится в `skills/ocx/LICENSE`, чтобы изменения лицензии
  были видны в vendored-наборе и review PR.

## Автоматическая проверка upstream

- `sync-ocx-skill.yml` проверяет изменения upstream независимо от релизной
  сборки и открывает/обновляет PR с результатом синхронизации. PR не создаётся,
  если скрипт обнаружил локальный конфликт или не может безопасно перенести
  файлы; workflow сообщает об ошибке, не перезаписывая файлы.
- `pull-request.yml` проверяет vendor drift информационно; сборка образа имеет
  независимый путь и не зависит от успешности такой проверки.
- Локальные команды для просмотра предложенных upstream-изменений:

```bash
scripts/sync-ocx-skill.sh --check
scripts/sync-ocx-skill.sh
git status --short -- skills/ocx
git diff -- skills/ocx

Перед merge проверьте diff и лицензионный notice.

## Ограничения

- Требуются сеть и `git`/`python3`; upstream `LICENSE` должен быть доступен.
- Обновление намеренно отказывается сливать при любой локальной правке
  upstream-owned файла: конфликт разбирается вручную, без эвристического merge.
- Дополнение `references/container-hub.md` создаётся и обновляется отдельно;
  скрипт его не читает и не перезаписывает.
- GitHub `GITHUB_TOKEN`-ом созданный PR обычно не запускает другие workflow
  автоматически. Для запуска CI потребуется ручной rerun либо отдельная
  настройка GitHub App/PAT с ограниченными правами; автоматический merge не
  включён.