opencode-config/docs/handoff/pr-146-clickable-steps.md

pr	title
146	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, нумерация авто-пересчитывается рендерером, но явные числа соответствуют порядку массива.