Добавить иерархические настройки Pohuy для Pi

extensions/README.md

@@ -1,6 +1,6 @@
-# Расширение для Pi
+# Расширение Pi
 
-Расширение [`pohuy.ts`](./pohuy.ts) добавляет команду `/pohuy` и интерактивные настройки источников стиля.
+[`pohuy.ts`](./pohuy.ts) добавляет команду `/pohuy` и меню настройки стиля.
 
 ## Установка
 
@@ -10,9 +10,9 @@ pi install git:github.com/smixs/pohuy
 
 После установки или обновления выполните `/reload`.
 
-## Команды и переключение режима
+## Команды
 
-`/pohuy` открывает настройки в TUI. Быстрые команды переключают калибр без открытия интерфейса:
+`/pohuy` открывает меню. Режим можно сменить без меню:
 
 ```text
 /pohuy lite
@@ -21,37 +21,79 @@ pi install git:github.com/smixs/pohuy
 /pohuy normal
 ```
 
-`normal` выключает стиль ответов и удаляет управляемый блок Pohuy из системного промпта.
+`normal` выключает стиль и удаляет управляемый блок Pohuy из системного промпта.
 
-Те же переключатели работают отдельными фразами:
+Те же действия доступны через фразы:
 
-- «та мне похуй» и «заебал» включают `full`;
-- «нормальный режим» и «хватит материться» выключают стиль.
+- "та мне похуй" и "заебал" включают `full`;
+- "нормальный режим" и "хватит материться" включают `normal`.
 
-Распознанная фраза работает как управляющая команда и не отправляется модели как пользовательский запрос.
+Расширение обрабатывает такую фразу как команду и не отправляет её модели.
 
 ## Настройки
 
-### Mode
+### Режим
 
-Выбирает `normal`, `lite`, `full` или `ultra`.
+Доступны `normal`, `lite`, `full` и `ultra`.
 
-### Source preset
+### Источники
 
-- `tier-defaults` использует стандартный набор секций выбранного уровня;
-- `custom` сохраняет пользовательский набор секций.
+`tier-defaults` выбирает стандартные секции текущего режима. `custom` хранит ручной выбор.
 
-Разделы `Skill`, `Dictionary` и `Scenes` позволяют независимо включать найденные секции из [`SKILL.md`](../skills/pohuy/SKILL.md), [`slovar.md`](../skills/pohuy/references/slovar.md) и [`sceny.md`](../skills/pohuy/references/sceny.md). Невыбранные дополнительные секции в системный промпт не попадают.
+Вкладки `Skill`, `Словарь` и `Сцены` строятся из следующих файлов:
 
-Выбранные источники компилируются без потери авторского материала:
+- [`SKILL.md`](docs://page/project/skills/pohuy/SKILL.md);
+- [`slovar.md`](docs://page/project/skills/pohuy/references/slovar.md);
+- [`sceny.md`](docs://page/project/skills/pohuy/references/sceny.md);
+- [`huenitiv.md`](docs://page/project/skills/pohuy/references/huenitiv.md).
 
-- если вместе с рабочим минимумом выбрана полная словарная категория, краткий вариант этой категории из минимума не дублируется;
-- в сценах с вариантами `lite`, `full` и `ultra` остаётся только пример активного уровня;
-- остальные примеры и выбранные сцены сохраняются полностью, без символьной обрезки, token cap или скрытого лимита количества.
+`Space` переключает запись, группу, сцену или ресурс. Родитель показывает состояние всех дочерних элементов: включено, выключено или частично.
+
+Отключение главного компонента прекращает добавление стилевых инструкций в контекст. Выбор словаря, сцен и хуенитивов при этом сохраняется.
+
+### Интерфейс
+
+Меню занимает доступную ширину и до 60% высоты терминала. Размер рамки не меняется при навигации. Списки и документы прокручиваются внутри неё.
+
+В широком терминале дерево и карточка видны одновременно. `Tab` и `Shift+Tab` меняют активную панель. `f` разворачивает её и возвращает разделённый вид.
+
+В узком терминале сначала видно дерево. `Tab` или `Enter` открывает карточку выбранного элемента. Повторный `Tab`, `Backspace` или `Esc` возвращает к дереву.
+
+Карточка показывает состояние, источник, описание и текст выбранного раздела. Для сцены выводится полный пример. Для группы сверху указан счётчик включённых дочерних элементов. Список потомков второй раз не печатается.
+
+Остальные действия:
+
+- `/` ищет по названиям, тексту, примерам, алиасам и путям;
+- `Enter` в результатах поиска показывает элемент в дереве;
+- `c` копирует путь и строку источника;
+- `←` или `h` возвращает к родителю либо сворачивает группу;
+- `→` или `l` раскрывает группу либо выбирает первый пункт;
+- `1`, `2`, `3` и `4` открывают вкладку напрямую;
+- `[` и `]` переключают вкладки;
+- `?` открывает полную справку по клавишам.
+
+Нижняя строка показывает действия для текущего экрана. Если места мало, второстепенные подсказки остаются в `?`.
+
+### Вкладка Skill
+
+Вкладка содержит главный компонент, рабочий словарь, сцены и хуенитивы. Карточка ресурса показывает его состояние, источник и текст файла. YAML frontmatter выводится отдельно. Многострочное поле `description` рендерится как Markdown-цитата.
+
+Хуенитивы по умолчанию включены в `ultra`. Их можно вручную включить в `lite` или `full` и выключить в любом режиме.
+
+`Enter` на рабочем словаре или сценах открывает соответствующую вкладку. Для переключения отдельной записи вернитесь в дерево, раскройте группу и нажмите `Space`.
+
+### Сборка инструкции
+
+Расширение сохраняет выбранный авторский текст без скрытой обрезки:
+
+- полная словарная категория заменяет её краткий вариант из рабочего минимума;
+- из вариантов сцены `lite`, `full` и `ultra` остаётся пример текущего режима;
+- хуенитивы добавляются текстом из `references/huenitiv.md`, а не ссылкой;
+- число примеров и сцен не ограничивается.
 
 ## Хранение настроек
 
-Выбор сохраняется глобально в `~/.pi/agent/settings.json` и действует после перезапуска Pi и в других проектах. Расширение изменяет только ключ `pohuy`:
+Настройки хранятся в `~/.pi/agent/settings.json` и действуют во всех проектах. Расширение изменяет только ключ `pohuy`:
 
 ```json
 {
@@ -61,9 +103,9 @@ pi install git:github.com/smixs/pohuy
 }
 ```
 
-Если `settings.json` содержит повреждённый JSON, расширение запускается с безопасными значениями по умолчанию. При следующем изменении настроек исходный файл сохраняется рядом как `settings.json.corrupt-*`, после чего записывается новый валидный файл.
+Если файл содержит некорректный JSON, расширение запускается со значениями по умолчанию. Перед следующей записью повреждённый файл переименовывается в `settings.json.corrupt-*`.
 
-Отсутствующий `selectedSections` использует defaults активного tier. Явный пустой массив отключает все дополнительные секции:
+Если `selectedSections` отсутствует, используются стандартные секции режима. Пустой массив отключает все дополнительные секции:
 
 ```json
 {
@@ -74,25 +116,49 @@ pi install git:github.com/smixs/pohuy
 }
 ```
 
-## Композиция системного промпта
+Изменения отдельных записей хранятся в `itemOverrides`. Ключ состоит из источника, раздела и нормализованного заголовка. Строка источника вычисляется при загрузке. Явно выключенный термин удаляется из всего управляемого блока, включая повторы в других секциях:
+
+```json
+{
+  "pohuy": {
+    "tier": "full",
+    "skillEnabled": true,
+    "itemOverrides": {
+      "item:slovar:Образность: восклицания, звукопись, присказки:опа! пиздрик": false
+    }
+  }
+}
+```
+
+`skillEnabled: false` выключает стиль, но не сбрасывает `selectedSections` и `itemOverrides`.
+
+## Системный промпт
 
-Расширение сохраняет уже собранный системный промпт Pi и помещает управляемый блок стиля непосредственно перед пользовательским `appendSystemPrompt`, когда такой сегмент присутствует. Оно не пересобирает базовый промпт, поэтому внутренние и сторонние context lanes остаются в исходном порядке.
+Расширение не пересобирает системный промпт Pi. Оно вставляет блок стиля перед `appendSystemPrompt`, если этот сегмент есть, и сохраняет порядок остального контекста.
 
-Управляемый блок ограничен маркерами:
+Блок ограничен маркерами:
 
 ```text
 <!-- POHUY:START -->
 ...
 <!-- POHUY:END -->
 ```
 
-Перед вставкой расширение удаляет все завершённые блоки между собственными маркерами и добавляет один текущий экземпляр. Это делает обработчик идемпотентным при повторных вызовах и не затрагивает текст без полного парного диапазона маркеров.
+Перед вставкой расширение удаляет завершённые блоки между этими маркерами и добавляет один актуальный блок. Непарные маркеры и чужой текст оно не трогает.
+
+Расширение удаляет только известные повторы между собственными источниками. Повторы во внешнем контексте должен устранять его владелец.
+
+## Код
+
+[`pohuy.ts`](./pohuy.ts) регистрирует события и команды Pi. Остальной код разделён по назначению:
 
-Расширение не дедуплицирует произвольные project context или session lanes. Оно устраняет только известные семантические пересечения собственных источников. Если одинаковый внешний контекст приходит из нескольких владельцев, его нормализация и provenance относятся к сборщику промпта Pi, а не к этому пакету.
+- [`pohuy/style-source.ts`](./pohuy/style-source.ts) читает Markdown, строит дерево и собирает инструкцию;
+- [`pohuy/settings-store.ts`](./pohuy/settings-store.ts) читает, нормализует и атомарно записывает настройки;
+- [`pohuy/settings-ui.ts`](./pohuy/settings-ui.ts) рендерит дерево, карточки, поиск и справку.
 
-## Ограничения стиля
+## Границы стиля
 
-Стиль применяется только к естественному тексту ответов. Tool calls, structured output, код, команды, идентификаторы, строки ошибок, коммиты, PR и документация сохраняют требуемый формат. Для security-предупреждений и подтверждения необратимых операций действует режим без юмора.
+Стиль меняет только обычный текст ответа. Он не меняет вызовы инструментов, структурированные данные, код, команды, идентификаторы, ошибки, коммиты, PR и документацию. Предупреждения безопасности и подтверждения необратимых операций остаются без юмора.
 
 ## Быстрая проверка
 
@@ -101,10 +167,10 @@ pi install git:github.com/smixs/pohuy
 Pohuy enabled: ultra.
 
 > объясни, почему тест флакает
-# ответ остаётся технически точным, но использует выбранный стиль
+# ответ остаётся технически точным и использует выбранный стиль
 
 > /pohuy normal
 Pohuy disabled. Normal mode restored.
 ```
 
-В RPC и других режимах без TUI команда `/pohuy` без аргумента выводит предупреждение; быстрые команды с аргументом продолжают работать.
+В RPC и других режимах без TUI команда `/pohuy` без аргумента выводит предупреждение. Команды с режимом продолжают работать.