diff --git a/docs/web-test-runner-spec.md b/docs/web-test-runner-spec.md
index 90faee48..f659b5fa 100644
--- a/docs/web-test-runner-spec.md
+++ b/docs/web-test-runner-spec.md
@@ -929,6 +929,44 @@ export default async function({ fillFields, getFormState, assert }, { type, fiel
 
 Полный регресс — **19/19** (~9 минут на warm-стенде).
 
+### 16.1. Вложенные каталоги
+
+Discovery (`run.mjs:900`) обходит дерево `testDir` рекурсивно, поэтому
+тесты можно раскладывать по подкаталогам без правок раннера:
+
+```
+tests/web-test/
+  sales/
+    01-order-create.test.mjs
+    02-order-post.test.mjs
+  warehouse/
+    01-receipt.test.mjs
+```
+
+**Что работает:**
+
+| Аспект | Поведение |
+|--------|-----------|
+| Обнаружение | Рекурсивный walk; файлы/каталоги на `_`/`.` пропускаются |
+| Порядок | `files.sort()` по полному относительному пути (`sales/01` идёт до `warehouse/01`) |
+| `file` в отчёте | `relative(testDir, file)` с `/`, например `sales/01-order-create.test.mjs` |
+| CLI-фильтр по пути | `node run.mjs test tests/web-test/sales/` запустит только подкаталог |
+| Конкретный файл | `node run.mjs test tests/web-test/sales/01-order-create.test.mjs` |
+
+**Что НЕ поддержано** (сознательно, чтобы держать модель простой):
+
+- **Per-folder `_hooks.mjs`.** Раннер ищет `_hooks.mjs` только в корне `testDir`. Подкаталоги свои хуки не получают.
+- **Per-folder `webtest.config.mjs`.** Тоже только в корне.
+- **Suite-концепция в отчётах.** Allure suite labels из дерева каталогов не строятся; группируйте через `tags`.
+- **Per-folder context default.** Каждый тест объявляет `context`/`contexts` сам; от пути контексты не наследуются.
+
+**Конвенции:**
+
+1. **Папки — для организации**, не для механики. Если хочется shared setup для «процесса» — клади в глобальный `_hooks.mjs.beforeAll` или в per-test `setup`/`teardown`.
+2. **Группировку в отчётах** делай через `tags: ['sales']`, не через путь. Это даёт фильтрацию (`--tags=sales`) и работает в Allure/JUnit без дополнительной разметки.
+3. **«Запустить только sales»** — двумя путями: `tests/web-test/sales/` (по каталогу) или `--tags=sales` (по тегу). Оба работают, выбирайте удобный.
+4. **Сортировка по полному пути** означает, что `warehouse/01-x` запустится ПОСЛЕ `sales/02-y`. Для строгого глобального порядка используйте 3-значные префиксы (`010-`/`020-`/...) либо явные теги-фазы.
+
 ---
 
 ## 17. Дорожная карта реализации