doc-folder

doc-folder — обзорный README.md для мульти-проектной папки

Когда срабатывать

Пользователь просит обзорную карту кода папки: «doc-folder», «сделай README для папки», «опиши проекты в каталоге», «обзор классов». Вывод — один README.md в корне указанной папки, а НЕ дока по классам (doc-md) и не /// (doc-cs).

Общий алгоритм (три прохода)

Pass 1 — обнаружение (главная сессия, Glob + Grep)

1. Аргумент — путь к папке. Если не передан — спроси путь.
2. Найди все .cs: Glob("<папка>/**/*.cs"). Исключи bin/, obj/ и сгенерированные файлы: *.g.cs, *.Designer.cs, *.AssemblyInfo.cs, *.AssemblyAttributes.cs.
3. Найди проекты: Glob("<папка>/**/*.csproj"). Для каждого определи имя (файл без расширения), корневую папку, root-namespace (<RootNamespace> или имя проекта), TargetFramework(s).
4. Привяжи каждый .cs к проекту по ближайшему .csproj вверх по дереву. .cs без проекта собери в группу «Вне проектов».
5. Извлеки из каждого .cs (Grep): namespace, ПУБЛИЧНЫЕ типы (public ... class|interface|enum|record|struct), базовый тип/интерфейсы, наличие /// <summary>. Только public — internal/private пропускай.
   • В одном .cs может быть несколько public-типов — делай запись на каждый тип, а не на файл.
   • Вложенные (nested) public-типы тоже включай. Grep по public … не отличает вложенные от верхнеуровневых — вложенность определяй при чтении тела типа в Pass 2 (по фигурным скобкам родителя).
   • Учитывай и file-scoped (namespace X;), и блочные (namespace X { }) объявления. Если namespace в файле нет (top-level statements) — тип относится к глобальному namespace проекта.

Pass 2 — описание классов (LLM; опц. субагенты ≤ 10)

Для каждого public-типа сформируй запись ~3-6 строк строго по references/class-summary-style-ru.md (прочитай файл до генерации): назначение (что класс делает в целом) + логика/роль + зависимости/использование. Без сигнатур методов и таблиц параметров.

Pass 3 — сборка README (главная сессия)

1. Собери README.md по assets/readme.md.template (структура ниже).
2. Если существуют documentation/api/ (от doc-md) или documentation/database.md (от doc-db) — добавь строку ссылок на них. Если их нет — строку не добавляй.
3. Запиши через Write в <указанная папка>/README.md. Файл всегда перезаписывается — это снимок текущего кода.

Структура README (проекты → namespace → классы)

• Frontmatter type: folder-overview (схема — ../doc-md/references/frontmatter-schema.md, единый источник истины).
• Шапка: назначение файла + дата генерации.
• Сводная таблица проектов: Проект | TFM | Namespace | Описание.
  • Описание проекта: бери <Description> из .csproj, если есть; иначе сформулируй сам по структуре и коду проекта.
  • Namespace в таблице: root-namespace проекта; если namespace-деклараций нет (top-level statements) — пиши (global).
• Раздел на каждый проект → подзаголовки по namespace → записи классов.
• Если в проекте один namespace (или его нет вовсе) — уровень группировки опусти, классы идут списком сразу под проектом.
• Вложенный тип ставь записью сразу ПОСЛЕ записи родительского типа.
• Если sub-namespace содержит один тип — не плоди отдельный заголовок: включи тип в ближайший родительский раздел, указав полный namespace в мета-строке записи (Слой: … · \Full.Sub.Namespace` · …`).
• Тестовые проекты включай; для тест-классов layer = test.

Полный шаблон — assets/readme.md.template. Пример записи класса:

#### `SvItemDao` — репозиторий справочника «Уровни доступа»
Слой: data-access · `Sample.Dico` · [`src/Dico/SvItemDao.cs`](src/Dico/SvItemDao.cs)

Инкапсулирует CRUD к таблице `DICT.SV_ITEM` через ADO.NET. `Insert` версионирует
запись через `SV_PREVIOUSID`, `GetAll` отдаёт только активные строки
(`SV_RECORDSTATUS = 1`). Зависит от `AppContext`, используется `AccessService`.

Обработка больших папок (параллелизм ≤ 10)

Опционально. Pass 1 и Pass 3 — всегда в главной сессии (один выходной файл, блоки склеивает главная). Pass 2 распараллеливай субагентами Task волнами не более 10: каждому передай его .cs-файлы и путь к references/class-summary-style-ru.md (обязан прочитать до генерации, иначе объём и стиль описаний разъедутся). Субагент возвращает готовые markdown-блоки классов — главная сессия компонует их в единый README.

Соглашения

• Язык вывода — русский; имена типов/членов/проектов — как в коде.
• Только public-типы. Не выдумывай назначение — лучше короче.
• Не воспроизводи сигнатуры методов и таблицы параметров (это doc-md).
• Относительные пути в ссылках считай от README.md в корне указанной папки.
• Ссылки на documentation/... ставь только если файлы существуют.
• Якоря для ссылок в таблице проектов формируй по правилу GitHub Markdown: нижний регистр, пробелы → -, точки и прочие спецсимволы убери (OllamaApiConsole → #ollamaapiconsole, My.Proj.Api → #myprojapi).

Когда отказаться

• Просят inline /// в .cs → doc-cs.
• Просят детальную доку по классу (.md на класс, таблицы методов) → doc-md.
• Просят описать схему БД → doc-db.