This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Для агентов

Правила для агентов, которые дорабатывают инструмент или его документацию. Полная версия — AGENTS.md в корне репозитория.

Продуктовая цель

Сотрудник подразделения Банка России без программирования должен:

1. настроить опрос за 30 минут по инструкции;
2. провести сессию, открыв одну ссылку;
3. получить ответы в таблице без ручной выгрузки.

Всё, что усложняет эти три пункта, — регресс, а не фича.

Три роли

Роль	Что делает	Что читает
Организатор	Настраивает один раз	Быстрый старт, Настройка по шагам
Ведущий	Проводит сессию	Проведение опроса
Доработчик	Правит код и документацию	Архитектура, эта страница

Тексты для ведущего и участника не должны содержать слов «скрипт», «API», «JSON», «развёртывание».

Правила

1. Простота важнее гибкости. Один путь настройки, минимум выборов, каждый шаг подтверждён скриншотом или проверкой «как понять, что получилось».
2. Не выдумывать. Лимиты, названия пунктов меню и возможности брать только из кода, скриншотов интерфейса и подтверждённых прогонов. Неизвестное помечать «уточнить».
3. Единый путь: Яндекс Формы → API. Альтернативные источники ответов — только запись в Дорожной карте, не ветвление инструкции.
4. Не трогать исходный контур КБР. Рабочие ресурсы КБР (tools/forms_response_receiver_codex.gs, tools/forms_response_analytics_codex.gs, таблица 1OcOXgzsilCd3CCfZ5SeU4WgmW-XjuBQfkE9yXxeayg4, design/codex/forms_20261027/) живут в cb/01_ACTIVE/ks-kbr-2026 и в этот репозиторий не входят.
5. Стиль — cb-bank-of-russia-style; названия пунктов меню — ровно как в русской локализации Google и Яндекс Форм.
6. Скриншот — часть инструкции. Новый шаг без иллюстрации не готов. Файлы в screenshots/ с именем step<N>_<тема>.png, секреты и личные имена замазаны.
7. Секреты. Реальный рабочий ключ КБР (f1a15a…) не должен встречаться в коде, документации и на скриншотах; в примерах — учебный ks-live-2026.
8. Минимальный дифф. Править только то, что относится к задаче; чужие формулировки не переписывать «своими словами». Перед правкой смотреть историю файла.
9. Синхронизация вики и docs/. Изменилось поведение продукта — обновляются обе ветки документации.

Проверки перед коммитом

node tests/test_code_gs.mjs     # обязательно при правке src/Code.gs

• все ссылки в README.md и docs/*.md ведут в существующие файлы или на внешние ресурсы;
• JSON-шаблоны валидны;
• после правки экрана — свежий скриншот результата.

Известные ловушки

Ловушка	Последствие
Символ % после среднего зашит в render()	Для безразмерной шкалы нужно убрать +'%'
Лист «Кодирование» читается как A2:C8	Восьмой вариант игнорируется
survey принимает только "1" и "2"	Третий опрос даёт Unknown survey
Имя HTML-файла должно быть LiveWidget	Другое имя → doGet не найдёт файл
После правки кода нужна новая версия развёртывания	Ссылка отдаёт старый код
SHEET_ID указывает на шаблон или не выполнена привязка копии (setupTemplate)	Опубликованный /exec не видит getActiveSpreadsheet() без сохранённого BOUND_SHEET_ID (или явного SHEET_ID копии); общий шаблон блокируется
vAxis диаграммы листа «Итоги» зафиксирован по минимуму	На больших объёмах проверять, что столбцы не обрезаются

Структура

Путь	Что лежит
src/Code.gs, src/LiveWidget.html	Продуктовый код
tests/test_code_gs.mjs	Автотест логики
docs/SETUP.md, RUNBOOK.md, TROUBLESHOOTING.md, FAQ.md, TECHNICAL.md, CUSTOM_QUESTIONS.md, ROADMAP.md	Документация в репозитории
screenshots/	Иллюстрации
README.md	Страница продукта
project.yaml	Метаданные для it/projects-hub
вики ks-live-survey.wiki.git	Основной пользовательский справочник

Ссылки в вики ведут на https://git.nb.vivo300.ru/valalav/ks-live-survey/.... При переносе репозитория в другую организацию их нужно обновить.