---
name: github-repo
description: Ведение репозитория GitHub как продукта — описание, темы, домашняя страница, README, гигиена файлов, релизы. Загружать, когда нужно оценить или переделать репозиторий, написать README, привести метаданные в порядок, проверить сообщество и ссылки перед публикацией.
---

# Репозиторий как продукт

## Когда загружать

- Репозиторий опубликован, но его «не видно»: описание из трёх слов, тем нет, README
  начинается с философии вместо установки.
- Нужен README, который читают до конца.
- Нужно проверить перед публикацией: файлы сообщества, лицензия, ссылки, бейджи.

## Первый вызов

```bash
python <pack>/tools/ghagent.py audit . --json
python <pack>/tools/ghagent.py audit --repo owner/name
```

`audit` отвечает одной структурой: оценка гигиены, список пунктов со статусом
`pass|fail|warn|skipped`, находки с `файл:строка`. Пункты, которые не удалось осмотреть,
попадают в `skipped` и **не** поднимают оценку.

## Что решает публикуемость

| Поле | Правило | Почему |
|---|---|---|
| `description` | категория впереди, до 200 символов, без эмодзи и превосходных степеней | поиск показывает первые ~120 символов |
| `topics` | 8–20, нижний регистр через дефис, главный термин первым | единственное структурированное поле ключевых слов |
| `homepage` | отвечает `200` или пусто | мёртвая ссылка хуже отсутствия |
| `LICENSE` | определяется GitHub: `license.spdx_id` не `NOASSERTION` | иначе проект юридически «нельзя использовать» |
| README | заголовок, абзац, бейджи, установка, использование, лицензия | первые 30 секунд решают, читать ли дальше |
| Wiki | `Home`, `_Sidebar`, `_Footer` | навигация превращает набор страниц в документацию |
| Release | тег `vX.Y.Z` и заметки | признак живого проекта |

## Порядок работы

1. `audit .` — где провал. Сначала `error`, потом `warn`.
2. README: взять `reference/readme-template.md`, заполнить фактами, проверить
   `ghagent doc --root .`.
3. Метаданные: `ghagent meta suggest`, затем `ghagent meta apply ... --write`.
4. Проверка после записи: `ghagent audit --repo owner/name --http`.
5. Отчёт: `ghagent report . --out AUDIT.md`.

## Ловушки

| Ловушка | Признак | Что делать |
|---|---|---|
| `PUT /topics` заменяет список | исчезли темы, которых не касались | слить с существующими, перечитать |
| Больше 20 тем | часть не сохранилась | оставить 20, главный термин первым |
| Pages в приватном репозитории | `422 Your current plan does not support GitHub Pages for this repository` | на бесплатном плане Pages недоступны |
| Сборка Pages асинхронна | сразу после включения 404 | ждать сборку, затем проверить URL |
| `gh api --jq .content` для README | base64 с переводами строк | `-H 'Accept: application/vnd.github.raw'` |
| Бейдж на несуществующий workflow | бейдж «не найден» | путь бейджа = путь workflow |

## Критерий готовности

- `ghagent audit .` — код `0`, оценка ≥ 80%.
- `ghagent audit --repo owner/name` — код `0`.
- В README каждое число имеет источник измерения.
- В описании нет ни одного слова, которое нельзя проверить.