---
name: repo-readme
description: Use when creating or updating README.md for any slaid098 repository. Calls create-readme tool for deterministic structure with delimiter tags for slaid098.dev showcase. Also when user says "оформи README", "обнови описание репо", "readme template", "базовая структура readme".
---

# Repo README

Стандартизация `README.md` во всех репозиториях slaid098 через тулзу
`create-readme`. Тулза гарантирует структуру (разделители, Features table,
Support block, Quick Start, language switcher). Скилл даёт контекст: когда
вызывать тулзу и какие параметры передавать.

## 1. Когда использовать тулзу

- **Новый репо** → `create-readme` (mode: `create`) — генерирует
  стандартизированный двуязычный README с нуля.
- **Проверка существующего README** → `.opencode/scripts/project-status.py`
  (`check_readme`) — проверяет, что структура соответствует стандарту витрины.
- **После ручных правок README** → всегда проверка через `check_readme`. Любая правка руками
  агента (через Edit/Write) может нарушить разделители — после правок
  обязательна проверка.

Не генерируй README вручную через Write — структура критична для парсинга
витриной. Только через тулзу `create-readme`.

## 2. GitHub metadata (отдельный шаг, НЕ в тулзе)

`create-readme` отвечает только за файл `README.md`. Метаданные репозитория
настраиваются отдельно через `gh repo edit` (это bash, не тулза):

- Описание: `gh repo edit --description "короткое описание"`
- Topics для поиска: `gh repo edit --add-topic topic1 --add-topic topic2`
- Social preview image — через настройки GitHub UI (не CLI).

Метаданные не дублируют README — они для карточки репо на GitHub и поиска.

## 3. Workflow

1. `create-readme` (mode: `create`) → генерирует README с гарантированной
   структурой (включая `![Cover](assets/cover.png)` после H1).
2. `draw-image` (template `"cover"`, slots по типу репо, `title`, `subtitle`,
   `out: "./assets/cover.png"`) → рендерит cover-изображение (1024×1024 PNG) на
   место, на которое ссылается README. Default `out` у `draw-image` уже
   `"./assets/cover.png"` — можно не передавать.
3. Ручные правки если нужно (агент редактирует файл напрямую через Edit) —
   например, расширить `custom_sections`, поправить формулировки.
4. Проверка через `.opencode/scripts/project-status.py` (`check_readme`) →
   структура соответствует стандарту витрины (в т.ч. наличие
   `assets/cover.png` reference).
5. Если проверка fails → фикс нарушения → повторная проверка. Цикл пока не
   пройдёт.

Локальный режим (по умолчанию): тулза пишет в `file_path` (default
`README.md`) через `fs.writeFileSync`, путь резолвится относительно
рабочей директории сессии (`context.worktree`) — существующий файл
перезаписывается. Удалённый режим: передай `repo`
(`owner/name`) — тулза сделает PUT через `gh api
repos/{owner}/{repo}/contents/README.md` с base64-контентом и SHA.

### Slot-выбор для cover

`draw-image` template `cover` имеет 3 опциональных слота. Значение slot —
либо имя Lucide-иконки (резолвится из `icons/lucide/<name>.svg`), либо имя
brand-logo (резолвится из `brand-logos/<name>.svg`), либо путь к файлу
(`./...` / `/...` / `../...`).

- `icon` — основная иконка (400×400, slot recolor=accent). Для репо,
  ассоциированных с продуктом/брендом — brand-logo (напр. `opencode`). Для
  утилит/SDK/скриптов — Lucide (напр. `square-terminal`, `code-xml`,
  `brain-circuit`).
- `sub-icon` — опциональная вторая иконка (200×200, recolor=accent). Lucide
  (напр. `git-branch`, `bot`, `terminal`).
- `badge` — опциональная третья иконка (180×180, bg=surface, border=accent,
  radius=0.5). Lucide или путь к файлу (напр. логотип-плашка).

Cover сохраняется в `assets/cover.png` (default `draw-image` out path).
README ссылается именно на этот путь через `![Cover](assets/cover.png)`.

## 4. Зачем разделители (контекст для агента)

Витрина **slaid098.dev** скачивает raw `README.md` из каждого репо и
извлекает фрагменты между разделителями:

- `<!-- tagline-en:start -->` ... `<!-- tagline-en:end -->` — английский
  tagline (короткая фраза для карточки).
- `<!-- tagline-ru:start -->` ... `<!-- tagline-ru:end -->` — русский
  tagline.
- `<!-- summary-en:start -->` ... `<!-- summary-en:end -->` — английский
  блок Why/What для карточки.
- `<!-- features-en:start -->` ... `<!-- features-en:end -->` — английская
  таблица фич.
- `<!-- summary-ru:start -->` ... `<!-- summary-ru:end -->` — русский блок
  Зачем/Что.
- `<!-- features-ru:start -->` ... `<!-- features-ru:end -->` — русская
  таблица фич.

Поэтому структура README **должна быть гарантирована тулзой**, а не агентом.
Агент может менять текст *внутри* разделителей, но не должен удалять/двигать
сами разделители. `check_readme` ловит такие нарушения.

## 5. Шаблон README (reference)

Тулза `create-readme` генерирует ровно эту структуру (параметры подставляются):

```markdown
# 🚀 {repo_name}

![Cover](assets/cover.png)

<!-- tagline-en:start -->
> {tagline_en}
<!-- tagline-en:end -->
<!-- tagline-ru:start -->
> {tagline_ru}
<!-- tagline-ru:end -->

[English](#-english) | [Русский](#-русский)

---

## 🇺🇸 English

<!-- summary-en:start -->
### ❓ Why
{why_en}

### ✅ What
{what_en}
<!-- summary-en:end -->

<!-- features-en:start -->
### Features

| Feature | Description |
|---------|-------------|
| {emoji} {name} | {description} |
...
<!-- features-en:end -->
{custom_sections_en — доп. секции, если переданы}

### ⚡ Quick Start
\`\`\`bash
{git clone строка, если include_clone !== false}
{quick_start}
\`\`\`
{quick_start_steps_en — нумерованный список кликабельных шагов, если передан: 1. ... 2. ...}
{access_url строка если передан — Access at [url](url), кликабельна}
{development_en блок, если передан — ### 🔧 Development + content}

---

## 🇷🇺 Русский

<!-- summary-ru:start -->
### ❓ Зачем
{why_ru}

### ✅ Что
{what_ru}
<!-- summary-ru:end -->

<!-- features-ru:start -->
### Фичи

| Фича | Описание |
|------|----------|
| {emoji} {name} | {description} |
...
<!-- features-ru:end -->
{custom_sections_ru — доп. секции, если переданы}

### ⚡ Быстрый старт
\`\`\`bash
{git clone строка, если include_clone !== false}
{quick_start}
\`\`\`
{quick_start_steps_ru — нумерованный список кликабельных шагов, если передан: 1. ... 2. ...}
{access_url строка если передан — Доступ: [url](url), кликабельна}
{development_ru блок, если передан — ### 🔧 Разработка + content}

---

## 💬 Support and contacts / Поддержка и контакты

👉 **[slaid098.dev/contacts](https://slaid098.dev/contacts)**
```

`check_readme` (project-status.py) проверяет: наличие всех 6 пар EN/RU
разделителей (tagline + summary + features), непустой контент между ними, H1
title prefix `# 🚀 `, **cover image
reference `assets/cover.png`** (substring-чек, без проверки существования
файла), ссылку
`slaid098.dev/contacts`, секции Quick Start (EN) и Быстрый старт (RU), language
switcher `[English]` / `[Русский]`, заголовок `## 🇷🇺 Русский` (не "Русская
версия"), anchor `[Русский](#-русский)` (не `#-русская-версия`). Флагирует
ручной заголовок `## License` / `## LICENSE` / `## Лицензия` как FAIL —
дубликат GitHub sidebar (GitHub рендерит license из LICENSE-файла). Шаги
`quick_start_steps_*` не влияют на валидацию — они рендерятся вне delimiter-пар
(summary/features).

## 6. Независимость от project-template

- Скилл `project-template` (init flow) создаёт проект через cookiecutter —
  шаблоны README.md НЕ содержат (issue #269): свежий проект рождается без
  README.
- `repo-readme` (через тулзу `create-readme`) **создаёт** полный README с нуля
  (delimiter tags, bilingual, cover) по ручному вызову после init.
- Может применяться к существующим репо без `project-template` — тулза
  перезапишет `README.md` (локально) или обновит через GitHub API (с SHA).

## 7. Параметры тулзы (кратко)

`create-readme`:

- `mode` — `"create"` (обязательный).
- `repo_name`, `tagline_en`, `tagline_ru`, `why_en`, `what_en`, `why_ru`,
  `what_ru`, `quick_start`, `features_en`, `features_ru` — обязательны для
  `create`.
- `repo_name` — должен быть **lowercase kebab-case** (regex
  `^[a-z0-9]+(-[a-z0-9]+)*$`): только `a-z`, `0-9`, одиночные дефисы. Uppercase,
  underscores, пробелы, leading/trailing/consecutive dashes — отвергаются.
- `tagline_en` — короткий английский tagline (1 предложение). **Не должен
  содержать кириллицы** (валидируется regex `/[ЁА-яё]/`).
- `tagline_ru` — короткий русский tagline (1 предложение). **Должен содержать
  кириллицу** (валидируется regex `/[ЁА-яё]/`). Гарантирует, что русский
  tagline реально на русском, а не копия английского.
- `features_en` / `features_ru` — массив `{ emoji, name, description }[]`.
- `custom_sections_en` / `custom_sections_ru` — массивы
  `{ title, content }` (optional).
- `access_url` — URL для Access/Доступ строки после Quick Start bash-блока
  (optional). EN: `Access at {url}`, RU: `Доступ: {url}`. Omit if no web access.
  Рендерится как markdown-ссылка `[url](url)` — кликабельна на GitHub.
- `include_clone` — boolean (optional, default true). `false` убирает `git clone`
  из Quick Start. Для userscript, web-app, npm-package.
- `quick_start_steps_en` / `quick_start_steps_ru` — массивы raw-markdown строк
  (optional). Каждая строка = один шаг, может содержать markdown-ссылки
  `[text](url)`. Рендерятся как нумерованный список `1. ... 2. ...` ПОСЛЕ
  bash-блока, ДО `access_url`. Кликабельные шаги для setup, где установка — это
  не одна команда, а несколько ссылок (установить userscript, получить API-ключ,
  настроить). Если массив пуст/не передан — шаги не рендерятся (backward compat).
- `development_en` — raw markdown (optional). `### 🔧 Development` после EN
  Quick Start, вне delimiter-тегов (не на slaid098.dev).
- `development_ru` — raw markdown (optional). `### 🔧 Разработка` после RU
  Быстрый старт, вне delimiter-тегов (не на slaid098.dev).
- `repo` — `owner/name` для удалённой операции (optional).
- `file_path` — локальный путь (default `README.md`).

## 8. Кейс: userscript / web-app / npm-package

Для репо без клонирования (userscript, web-app с demo URL, npm-package):

- `include_clone: false` — убирает `git clone` из Quick Start
- `quick_start` — команда установки (npm install, pip install, или ссылка на
  установку userscript). Если установка — это несколько ссылок (а не одна
  команда), лучше использовать `quick_start_steps_*` вместо/вместе с bash-блоком.
- `quick_start_steps_en` / `quick_start_steps_ru` — кликабельные шаги setup
  (рекомендуется для userscript/multi-step setup): установить userscript,
  получить API-ключ, настроить. Каждая строка может содержать `[text](url)`.
  Рендерятся как нумерованный список ПОСЛЕ bash-блока.
- `access_url` — URL web-доступа (если есть), рендерится как `[url](url)`.
- `development_en` / `development_ru` — инструкции для разработчиков (как
  собрать, как контрибьютить), рендерятся после Quick Start, вне
  delimiter-тегов (не на slaid098.dev)

### Пример: userscript со шагами-ссылками

```json
{
  "mode": "create",
  "repo_name": "my-userscript",
  "tagline_en": "One-line tagline.",
  "tagline_ru": "Короткий теглайн.",
  "why_en": "Why this exists.",
  "what_en": "What it does.",
  "why_ru": "Зачем этот проект.",
  "what_ru": "Что делает.",
  "quick_start": "",
  "include_clone": false,
  "features_en": [{ "emoji": "⚡", "name": "Fast", "description": "Instant setup" }],
  "features_ru": [{ "emoji": "⚡", "name": "Быстрый", "description": "Мгновенный старт" }],
  "access_url": "http://localhost:4096",
  "quick_start_steps_en": [
    "Install the [userscript](https://greasyfork.org/...)",
    "Get a [Groq API key](https://console.groq.com/keys)",
    "Configure [settings](https://example.com/settings)"
  ],
  "quick_start_steps_ru": [
    "Установи [юзерскрипт](https://greasyfork.org/...)",
    "Получи [ключ Groq](https://console.groq.com/keys)",
    "Настрой [параметры](https://example.com/settings)"
  ]
}
```

Результат (EN секция):

```markdown
### ⚡ Quick Start
1. Install the [userscript](https://greasyfork.org/...)
2. Get a [Groq API key](https://console.groq.com/keys)
3. Configure [settings](https://example.com/settings)

Access at [http://localhost:4096](http://localhost:4096)
```

`include_clone: false` + `quick_start: ""` → bash-блок не рендерится (только
шаги). Если `quick_start` непустой — bash-блок рендерится перед шагами.

## 9. Breaking change: tagline → tagline_en + tagline_ru

Параметр `tagline` **удалён** (PR #150). Раньше был один английский tagline;
теперь два — `tagline_en` (EN) и `tagline_ru` (RU) — оба обязательны для
`create`. Витрина slaid098.dev парсит оба через delimiter-теги
`<!-- tagline-en:start/end -->` и `<!-- tagline-ru:start/end -->`.

**Миграция:** замени `"tagline": "..."` на `"tagline_en": "..."` +
`"tagline_ru": "..."`. Старые вызовы с `tagline` падают с
`❌ tagline_en is required for create mode`.

**Существующие README** (без tagline delimiter-тегов) станут invalid при
проверке `check_readme` — `Missing <!-- tagline-en:start --> delimiter` и
`Missing <!-- tagline-ru:start --> delimiter`. Регенерация README через
`create` (с новыми параметрами) делается отдельным шагом после merge.
