Restructure software catalog

AGENTS.md

@@ -5,10 +5,10 @@
 
 ## Структура
 
-- Корень репозитория является корнем каталога; папку `catalog` создавать не
-  нужно.
-- Каждая категория и каждая программа находятся в собственной папке и содержат
-  ровно один файл `index.yaml`.
+- Все категории и программы находятся внутри корневой папки `catalog`.
+  `catalog/index.yaml` описывает корневую категорию.
+- Каждая категория и каждая программа внутри `catalog` находятся в собственной
+  папке и содержат ровно один файл `index.yaml`.
 - Вложенность категорий не ограничена. Дочерние категории и программы
   определяются по файловой структуре и не перечисляются в индексе категории.
 - Имя папки — стабильный идентификатор. Используй строчные латинские буквы,
@@ -28,9 +28,14 @@
 format: 1
 type: category
 name: Русское название категории
+order: -10
 description: Описание категории на русском языке.
 ```
 
+`order` — необязательное целое число для сортировки соседних категорий. Меньшее
+значение выводится раньше, отсутствие поля равнозначно `order: 0`. При равных
+значениях категории сортируются по названию. Располагай `order` после `name`.
+
 ## YAML программы
 
 Поля программы располагай в следующем порядке:
@@ -38,14 +43,16 @@ description: Описание категории на русском языке.
 1. `format: 1` — обязательное поле.
 2. `type: program` — обязательное поле.
 3. `name` — обязательное официальное название программы.
-4. `description` — обязательное подробное описание на русском языке в формате
+4. `summary` — обязательное короткое описание программы на русском языке.
+5. `description` — обязательное подробное описание на русском языке в формате
    Markdown.
-5. `homepage` — необязательный URL домашней страницы.
-6. `source` — необязательный URL исходного кода.
-7. `screenshots` — обязательный массив путей; используй `[]`, если изображений
+6. `homepage` — необязательный URL домашней страницы.
+7. `source` — необязательный URL исходного кода.
+8. `author` — необязательное имя автора или название организации-разработчика.
+9. `screenshots` — обязательный массив путей; используй `[]`, если изображений
    нет.
-8. `versions` — обязательный непустой массив версий.
-9. `additional_files` — необязательный массив файлов, не привязанных к версии.
+10. `versions` — обязательный непустой массив версий.
+11. `additional_files` — необязательный массив файлов, не привязанных к версии.
 
 Новые версии добавляй в начало `versions`, от новых к старым. Каждая версия
 имеет такой вид:
@@ -58,6 +65,7 @@ description: Описание категории на русском языке.
       - path: files/program-1.2.0.zip
         description: Назначение файла на русском языке
         platform: win32
+        size: 123456
         sha256: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
 ```
 
@@ -75,6 +83,19 @@ description: Описание категории на русском языке.
 `win64`, `dos`, `java` или `j2me`. Для Windows разрядность входит в название
 платформы; отдельное поле `architecture` не используется.
 
+Поля файла располагай в порядке `path`, `description`, `platform`, `size`,
+`sha256`. `size` содержит размер файла в байтах. Поля `size` и `sha256`
+заполняются командой `pnpm fill-metadata` и вручную не редактируются.
+
+### Короткое описание
+
+`summary` выводится рядом с названием программы в списке категории. Напиши
+естественное краткое описание, по которому понятно, что это за программа, для
+чего она нужна и с какими телефонами или форматами работает. Опирайся на полное
+описание и технический смысл программы, а не на единый шаблон. Не используй
+оценочные усилители вроде «комплексная», «универсальная», «мощная» или
+«полноценная».
+
 Файлы, которые подходят ко всем версиям или существуют отдельно от релиза,
 помещай в `additional_files`, а не внутрь случайной версии:
 
@@ -110,7 +131,8 @@ additional_files:
 - Абсолютные пути, `..` и обратная косая черта запрещены.
 - Каждый путь из YAML должен указывать на существующий файл.
 - Один файл нельзя одновременно указывать в `versions` и `additional_files`.
-- Для каждого добавленного файла вычисляй и указывай SHA-256 в нижнем регистре.
+- Для каждого добавленного файла указывай размер в байтах и SHA-256 в нижнем
+  регистре.
 - Архивы должны проходить через Git LFS согласно `.gitattributes`. Остальные
   файлы хранятся в обычном Git.
 
@@ -130,9 +152,10 @@ additional_files:
 1. Проверь синтаксис всех затронутых `index.yaml` безопасным YAML-парсером.
 2. Проверь их по `schema/index.schema.json` валидатором JSON Schema Draft 2020-12,
    если он доступен.
-3. Убедись, что все пути существуют и их SHA-256 совпадает с метаданными.
-   Для заполнения и обновления сумм используй `pnpm sha256 [путь]`, для проверки
-   без изменения файлов — `pnpm sha256:check [путь]`.
+3. Убедись, что все пути существуют, а их размеры и SHA-256 совпадают с
+   метаданными. Для заполнения и обновления используй
+   `pnpm fill-metadata [путь]`, для проверки без изменения файлов —
+   `pnpm fill-metadata:check [путь]`.
 4. Для каждого нового архива выполни `git check-attr filter -- <путь>` и
    убедись, что значение равно `lfs`.
 5. Выполни `git diff --check`.