Перевод английского нормативного контракта, сверенный с оригиналом в ревизии 61e75e9aa9a8719dfb480bf1f5226553b3a21d70. Перевод не является новой редакцией спецификации.

Контракт команды okf init

okf init <directory> [--json] создаёт новый набор документов OKF 0.2. Аргумент каталога обязателен и задаётся явно. Родительский каталог должен уже существовать. Команда не выбирает .okf в качестве пути по умолчанию: внутри существующего набора .okf зарезервирован для закрытого состояния хранилища.

Команда создаёт ровно два Markdown-файла в UTF-8:

Файл log.md не создаётся: искусственная запись об инициализации не добавила бы полезной истории. Шаблон не содержит выдуманных источников, подтверждения проверки, автора действия или временных метаданных. Замените черновик знаниями о вашей предметной области и добавляйте сведения о происхождении только на основании реальных материалов.

При успехе текстовый режим выводит Created OKF v0.2 bundle at <directory> с переводом строки в конце. Режим --json выводит один JSON-объект с полями path, okf_version и files (["index.md","getting-started.md"]). Значение path — переданный путь после лексической очистки; команда не преобразует его в абсолютный. При успехе код завершения равен 0, stderr пуст. Ошибки использования, файловой системы и публикации приводят к коду 1, одной строке error: ... в stderr и отсутствию вывода в stdout. Другие флаги и позиционные аргументы команда не принимает.

Целевой путь не должен существовать. Любой существующий файл, каталог — пустой или заполненный — либо символическая ссылка считается конфликтом, в том числе при повторном вызове. Флага --force нет. Команда подготавливает оба файла во временном соседнем каталоге со случайным именем, синхронизирует их и атомарно переименовывает готовый каталог в целевой, используя операцию публикации библиотеки, запрещающую замену существующего пути. Ошибка подготовки, отмена операции — включая SIGINT/SIGTERM до переименования — или конфликт при переименовании оставляет исходную цель нетронутой и не создаёт нового набора. Отмена по сигналу кооперативная: после переименования готовый набор уже может быть опубликован. Если синхронизация родительского каталога после переименования завершается ошибкой, сообщение явно указывает, что набор был опубликован; видимый набор полон, но может потребоваться проверка сохранности данных. Реализация не использует хранилище набора и не создаёт второй журнал.

Созданная заготовка проходит базовую проверку OKF. Строгая диагностика может рекомендовать дальнейшее заполнение; текст-заготовка намеренно не отмечен как проверенный.