soft/AGENTS.md

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

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

## Структура

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

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

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

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

`order` — необязательное целое число для сортировки соседних категорий. Меньшее
значение выводится раньше, отсутствие поля равнозначно `order: 0`. При равных
значениях категории сортируются по названию. Располагай `order` после `name`.

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

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

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

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

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

Поля файла располагай в порядке `path`, `description`, `platform`. Размеры и
SHA-256 не добавляй в индекс программы: они хранятся только в автоматически
создаваемом `catalog/files.yaml`.

### Короткое описание

`summary` выводится рядом с названием программы в списке категории. Напиши
естественное краткое описание, по которому понятно, что это за программа, для
чего она нужна и с какими телефонами или форматами работает. Опирайся на полное
описание и технический смысл программы, а не на единый шаблон. Не используй
оценочные усилители вроде «комплексная», «универсальная», «мощная» или
«полноценная».

Файлы, которые подходят ко всем версиям или существуют отдельно от релиза,
помещай в `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`.
- Дистрибутивы и отдельные исполняемые файлы храни в ZIP, совместимом со
  встроенным распаковщиком Windows XP: методы Store или Deflate, без шифрования
  и Zip64. Не добавляй RAR, 7z и незапакованные EXE.
- При перепаковке сохраняй имена, содержимое и время изменения файлов внутри
  архива.
- Архивы должны проходить через Git LFS согласно `.gitattributes`. Остальные
  файлы хранятся в обычном Git.

## Стиль YAML

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

## Проверка

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

1. Проверь синтаксис всех затронутых `index.yaml` безопасным YAML-парсером.
2. Проверь их по `schema/index.schema.json` валидатором JSON Schema Draft 2020-12,
   если он доступен.
3. Выполни `pnpm fill-metadata`, затем `pnpm fill-metadata:check`. Команда
   пересобирает `catalog/files.yaml` для всего каталога.
4. Для каждого нового архива выполни `git check-attr filter -- <путь>` и
   убедись, что значение равно `lfs`.
5. Выполни `git diff --check`.