# ADR-062: Clickable steps in Quick Start + conditional bash block (PR-146)

## Статус
Accepted (2026-07-29)

## Контекст
Тулза `create-readme` генерировала Quick Start как единый bash code-fence
(``` ```bash ... ``` ```) с опциональной плоской строкой `Access at {url}` /
`Доступ: {url}` после него. Два ограничения:

1. **Markdown-ссылки внутри code-fence не кликабельны** — для multi-step setup
   (userscript: установить скрипт → получить API-ключ → настроить) bash-блок
   не подходит: нужны кликабельные `[text](url)` шаги.
2. **Пустой bash-блок портил README** — при `quick_start` пустом и
   `include_clone=false` рендерился пустой ` ```bash ``` ` (визуальный мусор).
3. **`access_url` был bare URL** — авто-линк GitHub делает его кликабельным,
   но явная markdown-ссылка `[url](url)` надёжнее и в raw-просмотре.

## Решение
1. **Новые параметры** `quick_start_steps_en?: string[]` /
   `quick_start_steps_ru?: string[]` — массивы raw-markdown строк. Каждый
   элемент = один шаг, может содержать `[text](url)`.
2. **Helper `renderSteps(steps?)`** — возвращает `""` для пустого/undefined
   массива, иначе нумерованный список `\n1. ...\n2. ...\n` с пустыми строками
   вокруг (markdown-разделение от code-fence).
3. **Рендер шагов** — `${renderSteps(...)}` вставлен ПОСЛЕ bash-блока, ДО
   `accessLine*`, в обеих секциях (EN и RU).
4. **Условный bash-блок** — `hasBashBlock = include_clone !== false ||
   quick_start !== ""`. Если оба false → bash-fence не рендерится (только
   шаги, если есть). `cloneLine` вынесен в общую переменную. Default behavior
   сохранён (`include_clone` не передан → `!== false` → true → git clone).
5. **Кликабельный `access_url`** — `[url](url)` вместо bare URL.
6. **Валидатор** — без изменений: шаги вне delimiter-пар, секции "Quick Start" /
   "Быстрый старт" присутствуют всегда (заголовок рендерится независимо).

Backward compatibility: все существующие параметры/вызовы работают как раньше.
Новые параметры опциональны — если не переданы, Quick Start выглядит как
раньше (bash-блок + опциональный clickable `access_url`).

## Альтернативы
- **Шаги внутри code-fence** — отвергнуто: markdown-ссылки `[text](url)` НЕ
  кликабельны внутри ``` ```bash ``` (рендерятся как текст). Нужен
  нумерованный markdown-список вне code-fence.
- **Отдельный параметр `steps_mode: "bash" | "list"`** — отвергнуто: bash-блок
  и steps не взаимоисключающи. Можно рендерить bash-команду (установка) И шаги
  (получить ключ, настроить) вместе. Условный bash-блок через `hasBashBlock`
  покрывает все кейсы.
- **Ослабить required-чек `quick_start` в `execute()`** — отвергнуто: спека
  не просит менять required-валидацию. Сценарий "только шаги без bash" через
  `execute` требует `quick_start: ""` + `include_clone: false`, но `execute`
  отвергает пустой `quick_start`. `generateReadme` обрабатывает `quick_start=""
  ` корректно (bash не рендерится). Ослабление required — отдельное решение,
  вне scope этого PR.
- **Всегда рендерить bash-блок** — отвергнуто: пустой ` ```bash ``` ` портит
  README (исходная проблема). Условный рендер через `hasBashBlock` чище.
- **`access_url` как inline `[text](url)` с настраиваемым текстом** — отвергнуто:
  спека явно требует `[url](url)` (URL как text). Простой и предсказуемый.