Исправить в .env.example подсказку про админ-пароль, противоречащую коду

[Postlog]

Приоритет: low · Размер: XS · Бэклог-ранг: 20/20

Проблема

.env.example:13 гласит «Empty password disables the panel», но load.go:60-62 hard-fail'ит при пустом SUBGEN_ADMIN_PASSWORD, а AGENTS.md утверждает, что админка всегда включена (фичи «disable panel» нет). Точное следование документированному quick-start (cp, задать только SUBGEN_SECRET, запустить) делает так, что сервис отказывается стартовать. (Комментарий самого load.go:28 уже корректен — неверен только пример.)

Почему важно

Устаревшая подсказка ломает ровно тот документированный quick-start-путь и изобретает несуществующую фичу.

Предлагаемое решение

Исправить .env.example:13: убрать строку про «disables the panel» и указать, что SUBGEN_ADMIN_PASSWORD обязателен (без него сервис не стартует), с плейсхолдером; опционально отметить задание админ-пароля в README quick-start.

Затронутые файлы

• .env.example, README.md

---

_{Из аудита кодовой базы subgen (10 подсистем → adversarial-верификация, 71 находка). Бэклог-ранг указан для приоритизации.}

[Postlog]

🛠 План реализации

Резюме. Чистый docs-фикс: убрать из .env.example устаревшую подсказку «Empty password disables the panel» (фичи отключения панели нет — SUBGEN_ADMIN_PASSWORD обязателен, иначе сервис не стартует) и поправить README quick-start, который сейчас велит задать только SUBGEN_SECRET. Кода/миграций/OpenAPI не трогаем.

Сверка issue с кодом (факты репозитория)

• .env.example:13 — # Admin panel. Empty password disables the panel. — подтверждено. Подсказка ложная.
• internal/config/load.go:60-62 — validate() делает hard-fail при пустом SUBGEN_ADMIN_PASSWORD (return fmt.Errorf("SUBGEN_ADMIN_PASSWORD is required (gates the admin API)")). Подтверждено: «disable panel»-ветки нет.
• internal/config/load.go:28 — doc-комментарий уже корректен (SUBGEN_ADMIN_PASSWORD … admin password (required; gates the admin API)). Править НЕ нужно (совпадает с issue).
• AGENTS.md (строки ~189-192): «Admin всегда включён (SUBGEN_ADMIN_PASSWORD обязателен в конфиге; AdminEnabled/опциональной панели нет)». Подтверждает: подсказка про «disable» противоречит и коду, и конвенции.
• README.md:72 — quick-start cp .env.example .env # then set SUBGEN_SECRET (...) упоминает только SUBGEN_SECRET, не SUBGEN_ADMIN_PASSWORD. Это и есть «документированный quick-start», который ломается: go run ./cmd/service упадёт на validate. README.md:77 ссылается на пароль («admin / your SUBGEN_ADMIN_PASSWORD»), но не говорит его задать. Значит правка README уместна — issue называет файл в «Затронутые файлы».

Пошаговый план

Один слой — статика/docs. Снизу вверх неприменимо; два независимых файла.

1. /Users/postlog/programming/subgen/.env.example (строки 13-15).

   • Заменить вводящий в заблуждение комментарий # Admin panel. Empty password disables the panel. на корректный: пометить SUBGEN_ADMIN_PASSWORD как REQUIRED (как сделано для SUBGEN_SECRET на строке 8 — стиль # REQUIRED. …), указать, что без него сервис не стартует, и дать плейсхолдер-значение, чтобы скопированный .env стартовал из коробки.
   • Эскиз:

     # Admin panel credentials. SUBGEN_ADMIN_PASSWORD is REQUIRED — the service
     # refuses to start without it (it gates the admin API). There is no way to
     # disable the panel.
     SUBGEN_ADMIN_USER=admin
     SUBGEN_ADMIN_PASSWORD=change-me
     

   • Допущение: ставим непустой плейсхолдер (change-me), чтобы документированный quick-start (cp → задать SUBGEN_SECRET → go run) реально стартовал, не упираясь во второй обязательный пустой пароль. Это согласовано с тем, что SUBGEN_SECRET оставлен пустым намеренно (его нельзя осмысленно дефолтить — это HMAC-ключ; в quick-start его явно генерят openssl rand -hex 32). Альтернатива — оставить пустым и явно требовать заполнения в комментарии; выбираю плейсхолдер ради «копируется-и-работает».

2. /Users/postlog/programming/subgen/README.md (quick-start, строки 71-77).

   • В комментарии к cp .env.example .env (строка 72) дописать, что задать нужно и SUBGEN_ADMIN_PASSWORD (а не только SUBGEN_SECRET), либо сослаться, что плейсхолдер из .env.example уже годится для локалки. Привести текст в соответствие с тем, что без пароля старт падает.
   • Эскиз (строка 72):

     cp .env.example .env          # set SUBGEN_SECRET (openssl rand -hex 32);
                                   # SUBGEN_ADMIN_PASSWORD is required (placeholder is fine locally)
     

   • Строку 77 (admin / your SUBGEN_ADMIN_PASSWORD) можно оставить — она уже верна.

Миграции БД

Не требуются. Изменение касается только bootstrap-конфига (env), без структурных изменений БД.

OpenAPI/ogen

Не требуются. HTTP-контракт не меняется.

Тесты

Юнит-тесты не нужны: меняются только текстовые комментарии в .env.example и README.md, исполняемой логики нет. Контракт config.validate (SUBGEN_ADMIN_PASSWORD обязателен) уже отражает целевое поведение — правка лишь приводит документацию в соответствие с ним. Если в internal/config уже существует TestLoad/TestConfig_Load-таблица, опционально убедиться, что кейс error.empty_admin_password присутствует (по конвенции — один Test{Type}_{Method} на метод, table-driven); если кейса нет и он тривиально добавляется в существующую таблицу — добавить, но это не входит в скоуп issue. apitest не нужен (не wire-контракт ручки).

Документация

• CHANGELOG.md — одна запись наверх, формат ## YYYY-MM-DD — <заголовок> (#<PR>):

  ## 2026-06-12 — .env.example: убрана ложная подсказка про «disable panel» (#102)
  
  `SUBGEN_ADMIN_PASSWORD` помечен как обязательный (сервис не стартует без него),
  убрана несуществующая фича «Empty password disables the panel»; README quick-start
  приведён в соответствие (задать пароль, а не только SUBGEN_SECRET).
  

• ADR не нужен — тривиальное изменение (исправление устаревшего текста, нет развилок/трейд-оффов). Согласно AGENTS.md «Документирование изменений», для тривиальных изменений — только строка в CHANGELOG.

Риски и edge-cases

• Минимальный риск: правки текстовые. Проверить, что .env.example остаётся валидным для loadDotenv (internal/config/load.go:73): парсер берёт KEY=VALUE, режет #-комментарии и export , снимает обрамляющие кавычки. Плейсхолдер change-me без кавычек/пробелов парсится корректно.
• Не вводить в .env.example реальный пароль (секреты не коммитятся — раздел «Секреты — никогда в git»); change-me — очевидный плейсхолдер, не секрет.
• Не трогать load.go:28 (комментарий уже корректен) и саму validate() — issue про документацию, не про поведение.

Зависимости/порядок

Зависимостей от других issue нет. Самодостаточный XS-фикс.