docs: sync README and SPEC_EXPORT_DOCS with export_docs 0.3.12

Document flat-root pages, indexes, sidebar DFS tree, and link rewriting.

Co-authored-by: Cursor <cursoragent@cursor.com>

SPEC_EXPORT_DOCS.md

@@ -5,73 +5,94 @@
 Публикация аналитических Markdown-статей из рабочих каталогов проекта (`docs/` и др.) в wiki-репозиторий (`*.wiki.git`) с:
 
 - размещением в указанной папке wiki (`--folder`);
-- сохранением структуры подкаталогов по маске;
-- конвертацией локальных ссылок между выгружаемыми `.md`-файлами.
+- сохранением логической структуры подкаталогов (по умолчанию — плоские имена файлов);
+- конвертацией локальных ссылок между выгружаемыми `.md` и вложениями;
+- автоиндексами папок и навигацией в `Home` / `_Sidebar`.
 
 ## CLI
 
 ```bash
 python export_docs.py push \
   --files <glob> [<glob> ...] \
-  -s <path-to-src-or-config> \
-  --folder <wiki/subfolder> \
+  [--folder <wiki/subfolder>] \
+  [-s <path> | -c <path>] \
   [--wiki-url <repo.wiki.git>] [--remote origin] \
   [--work-dir <path>] [-o <path>] [--branch main] \
+  [-m "commit message"] [--dry-run] [--verbose] \
+  [--no-flat-root]
+
+python export_docs.py clean \
+  [--folder <wiki/subfolder>] \
+  [-s <path> | -c <path>] \
+  [--wiki-url <repo.wiki.git>] [--remote origin] \
+  [--work-dir <path>] [--branch main] \
   [-m "commit message"] [--dry-run]
 ```
 
 ## Параметры
 
-- `--files` (обяз.): одна или несколько glob-масок.
+- `--files` (только `push`, обяз.): одна или несколько glob-масок.
   - Экспортируются только `.md`.
   - Если маска указывает на каталог — берутся `**/*.md`.
   - Пример: `./docs/*.md`, `./docs/**/*.md`, `./reports`.
 - `-s/--src` или `-c/--config` (опц.): путь к конфигурации/`src` только для определения wiki URL по remote (аналогично `export_1c_help.py`).
-  - Если не указаны, анализируется текущая папка: берётся git remote текущей папки и из неё выводится `*.wiki.git`.
-- `--folder` (опц., по умолчанию `docs`): папка назначения в wiki, например `docs` или `migration/docs`.
-- `--wiki-url` (опц.): явный wiki URL; если не указан, выводится из `git remote` источника.
+  - Если не указаны, анализируется текущая папка: берётся git remote и из него выводится `*.wiki.git`.
+- `--folder` (опц., по умолчанию пусто = корень wiki): папка назначения, например `docs` или `migration/docs`.
+- `--wiki-url` (опц.): явный wiki URL; если не указан — из `git remote` источника.
+- `--no-flat-root`: оставить вложенные каталоги в wiki вместо имён `folder__sub__file.md`.
 - `--dry-run`: сборка + подготовка clone, без `git push`.
+- `--verbose`: печатать полный список входных аргументов `--files`.
+
+`clean` удаляет страницы из `manifest.export_docs.<hash(folder)>.json` и блок `<!-- export_docs:… -->` в `Home.md` / `_Sidebar.md`. Параметр `--files` не используется.
 
 ## Правила размещения файлов
 
 1. Для каждой маски определяется статический префикс (часть до wildcard).
 2. Для каждого совпавшего `.md` считается относительный путь от этого префикса.
 3. В wiki файл размещается как:
-   - `<folder>/<relative-path-from-pattern-root>`.
+   - **flat (по умолчанию):** `<folder>__<path>__<name>.md` (например `docs/transfer/a.md` → `docs__transfer__a.md`);
+   - **nested (`--no-flat-root`):** `<folder>/<relative-path-from-pattern-root>`.
 
-Примеры:
+Примеры (flat):
 
-- `--files ./docs/*.md --folder docs`
-  - `docs/a.md` → `docs/a.md`
-- `--files ./docs/**/*.md --folder migration/docs`
-  - `docs/plan.md` → `migration/docs/plan.md`
-  - `docs/phases/p1.md` → `migration/docs/phases/p1.md`
+- `--files ./docs/**/*.md --folder docs`
+  - `docs/plan.md` → `docs__plan.md`
+  - `docs/transfer/mapping/x.md` → `docs__transfer__mapping__x.md`
+
+## Индексы и навигация
+
+- На каждую папку с выгруженными статьями (и/или исходным `INDEX.md`) генерируется страница `…__INDEX` (или `…/INDEX.md` в nested-режиме).
+- В индексе: ссылка на родителя, список подпапок, список статей с полными заголовками (H1).
+- Исходный `INDEX.md` папки **не** дублируется как отдельная статья в списке — его тело (без ведущего H1) вшивается в автоиндекс.
+- В обычных статьях добавляется блок «вернуться в индекс папки».
+- В `Home.md` / `_Sidebar.md` вставляется/обновляется блок между маркерами `export_docs:begin` / `export_docs:end`.
+- `_Sidebar`: дерево папок в порядке родителя → дети (DFS); подпись — только имя сегмента (`📁 mapping`), без слова «Папка» и без полного пути.
 
 ## Конвертация ссылок
 
 Для Markdown-ссылок вида `[text](target)` и `![alt](target)`:
 
 - внешние URL (`http(s)`, `mailto`, `ftp`), якоря `#...`, абсолютные `/...` — без изменений;
-- относительные ссылки на выгружаемые `.md` пересчитываются на новый относительный путь между целевыми файлами в wiki;
-- ссылки на невыгружаемые файлы остаются как есть.
+- относительные ссылки на выгружаемые `.md` пересчитываются на целевой путь в wiki; в Markdown-цели **суффикс `.md` опускается** (Gitea: `/wiki/page`, не `/wiki/page.md`);
+- цели URL-кодируются (пробелы, скобки, кириллица);
+- локальные ссылки на файлы вне выгрузки, но внутри git-репозитория источника, переписываются в `https://…/src/branch/<branch>/<relpath>`;
+- прочие локальные файлы, попавшие в выгрузку как вложения, копируются, ссылки пересчитываются.
 
-Цель: сохранить ссылочность внутри набора опубликованных статей.
+Rewrite поддерживает inline и reference-style (`[id]: target`).
 
 ## Управление удалениями (без потери чужих wiki-страниц)
 
-Используется отдельный manifest для `export_docs` в корне wiki clone:
+Manifest в корне wiki clone: `manifest.export_docs.<hash(folder)>.json`.
 
-- `manifest.export_docs.<hash(folder)>.json`.
-
-При следующем запуске для того же `--folder`:
+При следующем `push` для того же `--folder`:
 
 - файлы из предыдущего manifest, которых нет в новой выгрузке, удаляются;
 - статьи/файлы, не управляемые этим manifest, не трогаются.
 
+Перед `git add` снимаются флаги `assume-unchanged` / `skip-worktree` с `Home.md` и `_Sidebar.md` (иначе Gitea-клон может не закоммитить правки навигации).
+
 ## Ограничения текущей версии
 
-- Автоматически обрабатываются только `.md` как источники выгрузки.
-- Вложения (картинки/файлы), на которые есть локальные ссылки в `[](...)` / `![](...)`, **копируются** в wiki вместе со статьями (с сохранением структуры каталогов относительно статического префикса маски).
-- Rewrite поддерживает как:
-  - inline-ссылки/картинки: `[](...)` и `![](...)`;
-  - reference-style определения: `[id]: target` (то есть ссылки вида `[text][id]` остаются рабочими, т.к. переопределения переписываются).
+- Источники выгрузки — только `.md`.
+- Вложения копируются только если на них есть локальная ссылка в выгружаемом Markdown.
+- Монтирование чужого дерева в подпапку wiki одной маской вида `ws:./ws-rhana/docs/**` пока не реализовано — используйте отдельные `--files` / `--folder` или ссылки на `src/branch/…`.