---
name: repo-images
description: Выбор, отрисовка и размещение картинок репозитория — социальное превью 1280×640, баннер в README, схема, скриншот — вместе с ограничениями платформы, которые решают, годится ли изображение. Загружать, когда у репозитория нет картинки, когда карточки ссылок пустые, когда изображение не отображается в вики или когда превью отклоняется при загрузке.
---

# Картинки для репозитория

Репозиторий без картинки читается как заброшенный. Социальное превью — это то, что показывают
карточки ссылок в чатах, почте и поиске; баннер — первое, что видит посетитель. Оба дешёвы в
производстве и легко ломаются, поэтому пакет отрисовывает их из метаданных проекта и затем
проверяет.

## Что принимает платформа

Проверено по документации GitHub «Customizing your repository's social media preview»:

| Свойство | Значение |
|---|---|
| Форматы | PNG, JPG или GIF |
| Размер файла | до 1 МБ |
| Минимум пикселей | 640×320 |
| Лучший вид | 1280×640 |
| Прозрачность | PNG с прозрачностью поддерживается |
| Где задаётся | Settings → Social preview → Edit → Upload an image |

SVG внутри README годится — GitHub его рендерит, — но **нельзя** загрузить как социальное
превью. Поэтому пакет пишет оба файла: `social-preview.png` для загрузки и
`social-preview.svg` как векторный двойник, которому ничего не нужно.

## Отрисовка

```bash
python <pack>/tools/ghagent.py assets render --title "Проект" \
    --tagline "Что делает и для кого, одним предложением." \
    --command "project --help" --chips "python,github,cli" --write
python <pack>/tools/ghagent.py assets check
```

| Флаг | Действие |
|---|---|
| `--title` | крупная строка; по умолчанию `H1` из README |
| `--tagline` | одна-две строки; по умолчанию абзац-описание из README |
| `--command` | моноширинная строка, обычно главная команда |
| `--chips` | ключевые слова через запятую, рисуются чипами |
| `--size` | `ШxВ`, по умолчанию `1280x640` |
| `--write` | действительно писать файлы; без флага — сухой прогон |

Результат: `assets/social-preview.svg` всегда, `assets/social-preview.png` — если установлен
Pillow. Без Pillow отчёт прямо говорит, почему PNG нет, а не делает вид, что превью готово.

## Размещение

```markdown
<img src="https://github.com/<owner>/<repo>/raw/main/assets/social-preview.png"
     alt="<Проект> — <что делает>" width="100%">
```

Правила проверки: баннер упомянут в README (`assets.readme-banner`), каждый упомянутый файл
существует (`assets.missing-file`), у картинки есть alt-текст (`assets.alt`, `md.image-alt`),
нет картинок по незащищённому `http://` (`md.image-http`), превью — PNG/JPG/GIF
(`assets.svg-social`), до 1 МБ (`assets.social-size`), не меньше 640×320 и лучше 1280×640
(`assets.social-dimensions`).

## Что ещё нужно репозиторию

`assets suggest` перечисляет виды изображений, уместные для этого дерева:

| Вид | Когда | Замечание |
|---|---|---|
| баннер / социальное превью | всегда | единственное, что отрисовывается без решений человека |
| схема | в проекте есть структура кода | предпочитать блок Mermaid: остаётся редактируемым |
| скриншот | есть интерфейс | 1440 px в ширину, персональные данные убраны |
| снимок терминала | есть CLI | лучше блоком кода, а не картинкой: остаётся в поиске |

## Ловушки

| Ловушка | Признак | Что делать |
|---|---|---|
| SVG предложен как превью | загрузка отклонена или карточка пустая | отрисовать PNG |
| Относительная картинка в вики | не отображается | вики не видит дерево репозитория: абсолютный URL |
| Файл закоммичен, карточка пустая | превью задаётся только в настройках | загрузить один раз вручную |
| Больше 1 МБ | загрузка падает | Pillow пишет оптимизированный PNG |
| На скриншоте реальные данные | утечка с долгой жизнью | синтетические данные, затем `privacy` |
| Текст «запечён» в картинку | не ищется и не переводится | текст в markdown, картинка показывает только изображение |

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

- `assets check` возвращает `0`.
- В README виден баннер, alt-текст объясняет, что на картинке.
- Файл превью 1280×640, до 1 МБ, загружен в настройках.
- Схема в README — блок Mermaid, если это возможно.