---
pr: 146
title: "feat(create-readme): add clickable steps to Quick Start"
---

## Что сделано
Расширение тулзы `create-readme` (`.opencode/tools/create-readme.ts`) —
кликабельные шаги-ссылки в Quick Start, условный bash-блок, кликабельный
`access_url`. Backward-compatible.

1. **Новые параметры** — `quick_start_steps_en?: string[]` и
   `quick_start_steps_ru?: string[]` добавлены в тип `CreateArgs` (строки 25-26)
   и в `tool.schema` (после `quick_start`, строки 214-220). Каждый элемент =
   raw-markdown строка, может содержать `[text](url)`. `.optional()`.
2. **Helper `renderSteps`** (строки 46-50) — если массив пуст/undefined → `""`,
   иначе нумерованный список `1. ...\n2. ...\n` с пустыми строками вокруг для
   markdown-разделения от code-fence.
3. **Рендер шагов** — `${renderSteps(args.quick_start_steps_*)}` вставлен после
   bash-блока, до `accessLine*` в обеих секциях (EN: строка 102, RU: строка 120).
4. **Условный bash-блок** — `hasBashBlock = include_clone !== false ||
   quick_start !== ""` (строка 70). Если оба условия false → bash-fence НЕ
   рендерится (только шаги). `cloneLine` вынесен в общую переменную (строки
   67-69). Применено к EN (`bashBlockEn`, строки 71-73) и RU (`bashBlockRu`,
   строки 74-76). Default behavior сохранён: `include_clone` не передан →
   `!== false` → true → git clone рендерится.
5. **Кликабельный `access_url`** (строки 59-60) — bare URL заменён на
   `[url](url)`. EN: `Access at [url](url)`, RU: `Доступ: [url](url)`.
6. **Передача параметров** — `quick_start_steps_en/ru` прокинуты в вызов
   `generateReadme({...})` в `execute()` (строки 324-325).
7. **Валидатор** — `validateReadme` НЕ изменён: шаги рендерятся вне delimiter-пар
   (summary/features) и не влияют ни на одну проверку (секции "Quick Start" /
   "Быстрый старт" присутствуют). Проверено smoke-тестом: все 28 checks PASS,
   `validate` проходит на всех сгенерированных README.
8. **Документация** — `.opencode/skills/repo-readme/SKILL.md` обновлён: новые
   параметры в секции 7, кликабельный `access_url` отмечен, reference-шаблон
   (секция 5) отражает шаги + clickable access, секция 8 (кейс userscript)
   расширена, добавлен пример вызова + ожидаемый вывод.

### Smoke-test
Прогнан через `npx tsx` с реальным `@opencode-ai/plugin` из
`.opencode/node_modules/` (mock не понадобился — плагин установлен). 5
сценариев, 28 assertions:
- S1: default (backward compat) — bash + git clone, no steps, no access.
- S2: steps + clickable access (main spec scenario) — вывод точно совпадает с
  примером из issue.
- S3: asymmetric (steps only on RU).
- S4: `include_clone=false` + non-empty `quick_start` → bash без git clone.
- S5: empty steps array → no list rendered.
Все `validate` PASS на сгенерированных README.

## Почему
Quick Start умел только bash-блок (markdown-ссылки внутри code-fence НЕ
кликабельны) и плоский `access_url`. Для multi-step setup (userscript:
установить → получить API-ключ → настроить) нужен нумерованный список
кликабельных шагов. Условный bash-блок убирает пустой ` ```bash ``` ` когда
установки нет (только шаги). Кликабельный `access_url` улучшает UX.

## Pending
—

## Watch out
- **`quick_start` остаётся required** для `create` mode в `execute()` (строки
  296-301). Сценарий "пустой quick_start + только steps" через `execute`
  невозможен без ослабления required-чеков — спека этого НЕ просит. Чтобы
  рендерить только шаги (без bash), передай `quick_start: ""` + `include_clone:
  false` — НО `execute` отвергнет пустой `quick_start`. Обход: передать
  минимальный `quick_start` (например пробел/коммент) или ослабить required в
  отдельном issue. В `generateReadme` напрямую логика `hasBashBlock` корректна
  для `quick_start=""`.
- **`access_url` визуально почти идентичен** на GitHub: был bare URL (auto-link)
  → стал `[url](url)` (markdown-ссылка). Оба кликабельны. На raw-text
  просмотрах (не GitHub) markdown-синтаксис виден.
- **tsconfig.smoke.json и smoke-harness** созданы в `/tmp/opencode/` (вне
  репо) — не коммитятся. Mock `@opencode-ai/plugin` не понадобился (реальный
  плагин установлен в `.opencode/node_modules/`, gitignored).
- **`renderSteps` использует `1-based` нумерацию** через `${i + 1}.` — markdown
  ordered list, нумерация авто-пересчитывается рендерером, но явные числа
  соответствуют порядку массива.