soft/AGENTS.md

# Правила ведения каталога

Эти правила действуют для всего репозитория. Перед изменением метаданных сверяйся
с `schema/index.schema.json`. Не добавляй поля, которых нет в схеме.

## Структура

- Корень репозитория является корнем каталога; папку `catalog` создавать не
  нужно.
- Каждая категория и каждая программа находятся в собственной папке и содержат
  ровно один файл `index.yaml`.
- Вложенность категорий не ограничена. Дочерние категории и программы
  определяются по файловой структуре и не перечисляются в индексе категории.
- Имя папки — стабильный идентификатор. Используй строчные латинские буквы,
  цифры, дефис и подчёркивание.
- В папке программы все загружаемые файлы находятся в `files`, а скриншоты — в
  `img`.
- Не создавай отдельные YAML-файлы или папки метаданных для версий. Все версии
  описываются в `versions` единственного `index.yaml` программы.
- Папки без `index.yaml`, например `schema`, `files` и `img`, не являются
  категориями.

## YAML категории

Используй только следующие обязательные поля и сохраняй их порядок:

```yaml
format: 1
type: category
name: Русское название категории
description: Описание категории на русском языке.
```

## YAML программы

Поля программы располагай в следующем порядке:

1. `format: 1` — обязательное поле.
2. `type: program` — обязательное поле.
3. `name` — обязательное официальное название программы.
4. `description` — обязательное подробное описание на русском языке в формате
   Markdown.
5. `homepage` — необязательный URL домашней страницы.
6. `source` — необязательный URL исходного кода.
7. `screenshots` — обязательный массив путей; используй `[]`, если изображений
   нет.
8. `versions` — обязательный непустой массив версий.
9. `additional_files` — необязательный массив файлов, не привязанных к версии.

Новые версии добавляй в начало `versions`, от новых к старым. Каждая версия
имеет такой вид:

```yaml
- version: "1.2.0"
  status: current
  released: "2007-08-14"
  files:
      - path: files/program-1.2.0.zip
        description: Назначение файла на русском языке
        platform: win32
        sha256: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
```

Поля версии располагай в порядке `version`, `status`, `released`, `description`,
`files`. Обязательны только `version` и непустой массив `files`. Необязательный
`status` принимает `current` для актуальной версии и `archived` для устаревшей,
сохранённой ради архива. Если статусы используются у программы, указывай их у
всех её версий. Поле `released` добавляй только при наличии достоверной даты.
Не переноси changelog в `description` версии и не добавляй это поле для полноты.
Оно допустимо только в особом случае, когда нужно зафиксировать существенное
ограничение, которое нельзя выразить номером версии или описанием конкретного
файла.

Необязательное поле файла `platform` принимает одно из значений: `win32`,
`win64`, `dos`, `java` или `j2me`. Для Windows разрядность входит в название
платформы; отдельное поле `architecture` не используется.

Файлы, которые подходят ко всем версиям или существуют отдельно от релиза,
помещай в `additional_files`, а не внутрь случайной версии:

```yaml
additional_files:
  - path: files/manual.pdf
    description: Руководство пользователя
```

## Текст и достоверность

- Названия категорий, описания программ, версий и файлов пиши на русском языке.
  Официальные названия продуктов и технологий не переводи.
- Сохраняй полноту исходного описания. Не сокращай перечень возможностей до
  общего пересказа и не удаляй значимые технические подробности.
- Содержимое каждого `description` интерпретируется как Markdown. Для длинного
  описания со списком используй литеральный блок `|-` и Markdown-списки; для
  обычного абзаца, перенесённого на несколько строк, используй `>-`. Не вставляй
  HTML-разметку.
- Не выдумывай даты, ссылки, возможности или платформы. Неизвестное
  необязательное поле лучше не добавлять.
- Сначала пытайся определить версию по странице, имени файла, README и
  метаданным бинарника. Если номер версии нигде не указан и достоверно получить
  его невозможно, используй каталоговое значение `version: "1.0"`. Не выводи
  номер версии из даты сборки.
- Если источник содержит только текущую версию, добавляй только её. Не ищи
  более ранние архивы в Wayback Machine без отдельного указания пользователя.

## Пути и файлы

- Все пути относительны папке программы и используют `/`.
- Путь загружаемого файла начинается с `files/`; путь скриншота — с `img/`.
- Абсолютные пути, `..` и обратная косая черта запрещены.
- Каждый путь из YAML должен указывать на существующий файл.
- Один файл нельзя одновременно указывать в `versions` и `additional_files`.
- Для каждого добавленного файла вычисляй и указывай SHA-256 в нижнем регистре.
- Архивы должны проходить через Git LFS согласно `.gitattributes`. Остальные
  файлы хранятся в обычном Git.

## Стиль YAML

- Кодировка — UTF-8, окончания строк — LF, отступ — два пробела, табуляция
  запрещена.
- Версии и даты всегда заключай в двойные кавычки.
- Дата имеет формат `YYYY-MM-DD`, SHA-256 — ровно 64 шестнадцатеричных символа.
- Не используй YAML-теги, anchors, aliases и merge keys.
- Не допускай неизвестных полей и дубликатов в массивах.

## Проверка

Перед завершением изменения:

1. Проверь синтаксис всех затронутых `index.yaml` безопасным YAML-парсером.
2. Проверь их по `schema/index.schema.json` валидатором JSON Schema Draft 2020-12,
   если он доступен.
3. Убедись, что все пути существуют и их SHA-256 совпадает с метаданными.
   Для заполнения и обновления сумм используй `pnpm sha256 [путь]`, для проверки
   без изменения файлов — `pnpm sha256:check [путь]`.
4. Для каждого нового архива выполни `git check-attr filter -- <путь>` и
   убедись, что значение равно `lfs`.
5. Выполни `git diff --check`.