@sberbusiness/triplex-next-mcp-server 1.43.0-beta → 1.45.0-beta

package/bundle/components/TreeViewNode.md

@@ -0,0 +1,436 @@
+---
+component: TreeViewNode
+category: TreeView
+related: [TreeView]
+tokens: []
+stories: stories/TreeView/TreeView.stories.tsx
+version: "1.0"
+---
+
+# TreeViewNode
+
+## Назначение
+
+Узел визуального дерева `TreeView` (доступен также как `TreeView.Node`). Рендерит
+`<li role="treeitem">` с `aria-expanded` и `tabIndex`, регистрирует себя в
+абстрактном дереве `TreeView`, обрабатывает `focus`/`blur` для перемещения
+активной ноды с клавиатуры и отдаёт потребителю пять provide-props через
+render-функцию `children`.
+
+Собственного оформления у ноды нет: она добавляет только семантику и сброс
+маркеров списка — всю разметку узла (шеврон, подпись, линии-коннекторы,
+подсветку активного состояния) рисует потребитель.
+
+Используй когда: строишь дерево на `TreeView` и нужен полный контроль над
+разметкой узла.
+
+Не используй когда:
+- нужно типовое дерево «папка/файл» с шевроном, hover и focus-visible — бери
+  `CollapsibleTree`;
+- нужен свой UI узла, но с анимацией раскрытия и controlled/uncontrolled
+  состоянием — бери `CollapsibleTreeExtended`, он оборачивает `TreeView.Node`
+  и добавляет accordion-логику;
+- узел нужен вне `TreeView` — вне провайдера контекста нода получает
+  `initialTreeContext`, где `registerNode` и остальные методы пустые: `<li>`
+  отрисуется, но в дерево нода не попадёт, `tabIndex` останется `-1`,
+  `hasChildNodes` всегда будет `false` (дети не регистрируются), а
+  `isLastNode` — всегда `true` (у ноды нет родителя).
+
+---
+
+## Варианты и props
+
+Экспортируемый `TreeViewNode` — это `withTreeViewContext(TreeViewNodeWithContext)`,
+то есть class-компонент, обёрнутый HOC-ом контекста. Prop `treeViewContext`
+подставляет HOC, снаружи его передавать не нужно.
+
+### Обязательные props
+
+| Prop | Тип | Описание |
+|---|---|---|
+| `id` | `string` | Идентификатор ноды, уникальный в пределах дерева. По нему абстрактное дерево ищет и связывает ноды, на него ссылаются `prevNodeId` / `nextNodeId` соседей |
+| `children` | `(props: ITreeViewNodeProvideProps) => JSX.Element` | Render-функция разметки узла. Не ReactNode: нода отдаёт своё состояние только через аргумент |
+
+### Опциональные props
+
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `opened` | `boolean` | `false` | Состояние раскрытия. Синхронизируется в абстрактное дерево в конструкторе и далее в `componentDidUpdate` при смене значения |
+| `prevNodeId` | `string` | — | Id ноды, после которой вставить текущую в абстрактное дерево |
+| `nextNodeId` | `string` | — | Id ноды, перед которой вставить текущую в абстрактное дерево |
+| `...HTMLAttributes` | — | — | Уходят на `<li>`. `className` мерджится с собственным классом, `onFocus` / `onBlur` вызываются после внутренних обработчиков |
+
+`ITreeViewNodeProps` расширяет `Omit<React.HTMLAttributes<HTMLElement>, "children">` —
+`children` переопределён под render-функцию намеренно.
+
+### Provide-props render-функции (`ITreeViewNodeProvideProps`)
+
+| Поле | Описание |
+|---|---|
+| `activeNode` | Нода активна при перемещении с клавиатуры. Подсветку рисует потребитель |
+| `openedNode` | Нода раскрыта — значение из абстрактного дерева, а не из prop `opened` |
+| `hasChildNodes` | У ноды есть **зарегистрированные** дочерние ноды |
+| `isLastNode` | Нода последняя в дереве целиком (последняя на своём уровне и все её предки — последние). Используется для линий-коннекторов |
+| `setOpenedNode(opened)` | Пишет флаг раскрытия в абстрактную ноду и инкрементит `updateCount` в `TreeView` для перерендера. Uncontrolled-путь: prop `opened` при этом не меняется |
+
+### Порядок нод и `prevNodeId` / `nextNodeId`
+
+Абстрактное дерево заполняется в **конструкторах** нод, то есть в порядке
+рендера. `prevNodeId` / `nextNodeId` позволяют вставить ноду в произвольное
+место уровня: порядок в абстрактном дереве (а значит `isLastNode` и порядок
+обхода стрелками) может отличаться от порядка в разметке. Ссылаться можно
+только на **уже зарегистрированную** ноду: к моменту конструктора текущей ноды
+конструктор соседа должен был отработать — монтирование при этом не требуется,
+оно происходит позже. Id соседей выводят из массива данных
+`CollapsibleTree` и `CheckboxTree`; `CollapsibleTreeExtended` своего массива не
+имеет и пробрасывает `prevNodeId` / `nextNodeId` как есть от потребителя.
+
+Промаха по id компонент не сигнализирует, но два случая промаха ведут себя
+по-разному. Ноду с указанным id ищут **в поддереве текущего родителя**, а не по
+всему дереву.
+
+- **Id не найден** — нода добавляется в конец своего уровня, то есть в порядке
+  рендера. Детерминированно и безопасно; это штатный режим, а не ошибка.
+  Именно так работает `nextNodeId` в `CollapsibleTree` и `CheckboxTree`: они
+  передают id следующей ноды из массива данных, а та на момент конструктора
+  текущей ещё не зарегистрирована — промах и откат в порядок рендера здесь
+  происходят всегда.
+- **Id найден, но это не прямой ребёнок того же родителя** — позиция
+  определяется индексной арифметикой `splice` в `AbstractTreeNode.addChild`.
+  Это **деталь текущей реализации, а не контракт**: тестами не закреплена,
+  класс общий для всех абстрактных деревьев, полагаться нельзя.
+
+Правильное употребление одно: ссылаться на уже зарегистрированную соседнюю ноду
+того же уровня.
+
+### Раскрытие и регистрация детей
+
+`hasChildNodes` вычисляется по абстрактному дереву, поэтому дочерние ноды
+должны быть **смонтированы**. Если размонтировать `TreeView.Group` в свёрнутом
+состоянии, родитель получит `hasChildNodes === false` и, например, не отрисует
+шеврон. Рабочий приём (используется в stories и в `CollapsibleTreeExtended`) —
+держать группу в разметке всегда, скрывая её стилями.
+
+---
+
+## Дизайн-токены
+
+Собственных CSS-переменных нода не определяет. Класс `treeViewNode` в
+`styles/TreeView.module.less` задаёт только сброс отступов и маркера списка
+плюс `outline: none` — focus-стиль рисует потребитель.
+
+---
+
+## Инварианты
+
+- **`TreeViewNodeWithContext` — class-компонент, и `forwardRef` на нём нет.**
+  Регистрация в абстрактном дереве происходит в **конструкторе** (до маунта
+  детей), а снятие — в `componentWillUnmount`; порядок этих вызовов и есть
+  порядок нод в дереве. Перевод на функциональный компонент меняет момент
+  регистрации и ломает `prevNodeId` / `nextNodeId`. Не мигрировать без
+  отдельного решения мейнтейнера.
+- **Корневой DOM-элемент — `<li>`.** Менять тег нельзя: `role="treeitem"`
+  валиден только внутри `<ul role="tree">` / `<ul role="group">`.
+- **`role="treeitem"` и `aria-expanded` выставляются после `{...props}`** —
+  семантика узла часть контракта компонента, потребитель её не переопределяет.
+  `tabIndex` остаётся **до** спреда: roving tabindex — поведение, а не
+  семантика, и потребитель при желании может задать его сам. Но переданный
+  `tabIndex` побеждает навсегда: `TreeView.updateTabIndexNodes` продолжит
+  пересчитывать значение в абстрактной ноде, на DOM это уже не повлияет. Поставив
+  `tabIndex={0}` всем нодам, потребитель получит не свой roving tabindex, а
+  дерево, где каждая нода — отдельная остановка Tab. Переопределять — только если
+  берёшь управление фокусом целиком на себя.
+- **`event.stopPropagation()` в `handleFocus` / `handleBlur` обязателен.**
+  `focusin` всплывает, и без остановки активной становилась бы не текущая нода,
+  а её родитель. Пользовательские `onFocus` / `onBlur` вызываются после
+  внутренней логики — порядок менять нельзя.
+- **`children` — функция, а не `ReactNode`.** Смена сигнатуры — breaking change
+  для всей цепочки потребителей. Напрямую `TreeView.Node` рендерит только
+  `CollapsibleTreeExtended`; `CollapsibleTree` строится поверх него, а
+  `CheckboxTree` доходит до ноды через `CheckboxTreeExtended` →
+  `CollapsibleTreeExtended`.
+- **Barrel `src/components/TreeView/index.ts`** реэкспортирует модуль ноды
+  целиком (`export * from "./components/TreeViewNode"`), поэтому публичны и
+  `TreeViewNode`, и класс `TreeViewNodeWithContext`, и типы
+  `ITreeViewNodeProps`, `ITreeViewNodeProvideProps`,
+  `ITreeViewNodePropsWithContext` — всё это через `src/components/index.ts`
+  доходит до корня пакета. Состав и имена менять нельзя.
+- **`displayName` класса — `"TreeViewNodeWithContext"`**, у экспортируемой
+  обёртки — `"WithTreeViewContext(TreeViewNodeWithContext)"` (добавляет HOC).
+  Значения видны в React DevTools и в snapshot-тестах.
+- **Абстрактная нода мутируемая.** `this.abstractNode` меняется на месте, и сам
+  по себе перерендер не вызывает: любая мутация должна идти через методы
+  контекста (`setOpenedNode`, `setActiveNode`, `registerNode`, `removeNode`),
+  которые инкрементят `updateCount` в состоянии `TreeView`. Прямая запись в
+  `abstractNode` в обход контекста оставит ноду с устаревшими
+  `hasChildNodes` / `isLastNode`.
+
+---
+
+## Accessibility
+
+Ориентир — WAI-ARIA Authoring Practices,
+[treeview-2a](https://www.w3.org/TR/wai-aria-practices-1.1/examples/treeview/treeview-2/treeview-2a.html).
+
+- Узел — `<li role="treeitem">` с `aria-expanded`, отражающим состояние
+  раскрытия из абстрактного дерева. Вложенные ноды оборачиваются в
+  `TreeView.Group` (`<ul role="group">`).
+- **Roving tabindex.** `tabIndex` нода читает из абстрактной ноды
+  (`getTabIndex()`): первая нода первого уровня получает `0`, остальные `-1`.
+  Пересчитывает значения `TreeView` при регистрации и удалении нод — в дерево
+  можно попасть одним Tab.
+- **Активная нода ≠ DOM-фокус.** Активной нода становится по `focus`, а стрелки
+  (`ArrowDown` / `ArrowUp`, обрабатываются в `TreeView` на `window`) двигают
+  только флаг активности в абстрактном дереве — DOM-фокус остаётся на исходном
+  узле. Потребитель обязан визуально отрисовать активное состояние по
+  provide-prop `activeNode`, иначе клавиатурная навигация не видна.
+- `blur` снимает активность; когда активной ноды в дереве не остаётся,
+  `TreeView` отписывает слушатель стрелок.
+- Раскрытие/сворачивание по клавиатуре (`ArrowRight` / `ArrowLeft`,
+  `Home` / `End`) нода **не** реализует — это на потребителе, в его разметке
+  узла.
+- Текстовые подписи и `aria-label` нода не хардкодит: библиотека мультиязычная,
+  всю разметку узла даёт потребитель. `aria-label` на дерево вешается на
+  `TreeView`.
+
+---
+
+## Связанные компоненты
+
+- `TreeView` (`src/components/TreeView`) — родительский компонент и владелец
+  абстрактного дерева: регистрирует ноды, считает `tabIndex`, обрабатывает
+  стрелки. Нода без него не работает.
+- `TreeViewGroup` (`TreeView.Group`) — `<ul role="group">`, обёртка вложенных
+  нод. Тривиальная обёртка (`forwardRef` + `clsx` + спред), отдельного AI.md
+  нет.
+- `CollapsibleTreeExtended` (`src/components/CollapsibleTreeExtended`) — обёртка
+  над `TreeView.Node`, добавляющая анимацию раскрытия и
+  controlled/uncontrolled состояние. Берут вместо голой ноды, когда свой UI
+  узла нужен, а возиться с состоянием — нет.
+- `CollapsibleTree` (`src/components/CollapsibleTree`) и `CheckboxTree`
+  (`src/components/CheckboxTree`) — готовые деревья поверх ноды; оба
+  протаскивают `prevNodeId` / `nextNodeId` из массива данных.
+
+---
+
+## Stories
+
+Отдельных stories у ноды нет: без `TreeView` она не рендерится, а собственного
+оформления у неё нет — все её состояния показаны в stories родителя. Ниже —
+только те, что демонстрируют API самой ноды; полный список историй семейства
+(`Playground`, `Default`) — в [TreeView-ai.md](./TreeView-ai.md).
+
+Основные истории: `stories/TreeView/TreeView.stories.tsx`
+Файлы примеров: `stories/TreeView/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Nested` | `Nested.tsx` | Вложенность через `TreeView.Group`, prop `opened`, provide-props `openedNode` и `hasChildNodes` |
+| `Keyboard navigation` | `KeyboardNavigation.tsx` | Перемещение `activeNode` стрелками, подсветка активной ноды, `isLastNode` |
+| `VisualTests` | `VisualTests.tsx` | Свёрнутая и раскрытая нода, узел с детьми и лист, `isLastNode`; активная нода снимается через `play` |
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-08-26 | Создан документ. Описание ноды вынесено из `TreeView-ai.md`. Добавлен unit-тест на `prevNodeId` — единственный публичный prop ноды, не покрытый тестами |
+
+---
+
+## Примеры использования
+
+### Nested
+
+`stories/TreeView/examples/Nested.tsx`
+
+```tsx
+import React from "react";
+import clsx from "clsx";
+import { CaretrightStrokeSrvIcon24 } from "@sberbusiness/icons-next";
+import { ETextSize, Text, TreeView } from "@sberbusiness/triplex-next";
+import "./Nested.less";
+
+interface INodeData {
+    id: string;
+    label: string;
+    children?: INodeData[];
+}
+
+const nodes: INodeData[] = [
+    {
+        id: "folder-1",
+        label: "Folder text",
+        children: [
+            { id: "file-1-1", label: "File text" },
+            { id: "file-1-2", label: "File text" },
+        ],
+    },
+    {
+        id: "folder-2",
+        label: "Folder text",
+        children: [
+            {
+                id: "folder-2-1",
+                label: "Folder text",
+                children: [{ id: "file-2-1-1", label: "File text" }],
+            },
+        ],
+    },
+    { id: "file-3", label: "File text" },
+];
+
+interface ITreeNodeProps {
+    node: INodeData;
+}
+
+const TreeNode = ({ node }: ITreeNodeProps) => {
+    const [opened, setOpened] = React.useState(false);
+    const branch = Boolean(node.children?.length);
+
+    const toggle = () => setOpened((prevOpened) => !prevOpened);
+
+    const handleClick = (event: React.MouseEvent<HTMLElement>) => {
+        // Клик по вложенной ноде не должен раскрывать родительскую.
+        event.stopPropagation();
+
+        if (branch) {
+            toggle();
+        }
+    };
+
+    const handleKeyDown = (event: React.KeyboardEvent<HTMLElement>) => {
+        if (event.key !== "Enter" && event.key !== " ") {
+            return;
+        }
+
+        event.preventDefault();
+        event.stopPropagation();
+
+        if (branch) {
+            toggle();
+        }
+    };
+
+    return (
+        <TreeView.Node id={node.id} opened={opened} onClick={handleClick} onKeyDown={handleKeyDown}>
+            {({ hasChildNodes, openedNode }) => (
+                <>
+                    <div className={clsx("tree-view-nested-example-row", { branch })}>
+                        {hasChildNodes ? (
+                            <CaretrightStrokeSrvIcon24
+                                paletteIndex={5}
+                                className={clsx("tree-view-nested-example-chevron", { opened: openedNode })}
+                                aria-hidden
+                            />
+                        ) : (
+                            <span className="tree-view-nested-example-chevron-placeholder" />
+                        )}
+                        <Text size={ETextSize.B1} tag="span">
+                            {node.label}
+                        </Text>
+                    </div>
+                    {node.children ? (
+                        // Группа остаётся смонтированной: так вложенные ноды зарегистрированы в дереве
+                        // и родитель знает про hasChildNodes даже в свёрнутом состоянии.
+                        <TreeView.Group className={clsx("tree-view-nested-example-group", { collapsed: !openedNode })}>
+                            {node.children.map((child) => (
+                                <TreeNode key={child.id} node={child} />
+                            ))}
+                        </TreeView.Group>
+                    ) : null}
+                </>
+            )}
+        </TreeView.Node>
+    );
+};
+
+export const Nested = () => (
+    <div className="tree-view-nested-example" style={{ maxWidth: 420 }}>
+        <TreeView aria-label="Tree">
+            {nodes.map((node) => (
+                <TreeNode key={node.id} node={node} />
+            ))}
+        </TreeView>
+    </div>
+);
+```
+
+### Keyboard navigation
+
+`stories/TreeView/examples/KeyboardNavigation.tsx`
+
+```tsx
+import React from "react";
+import clsx from "clsx";
+import { ECaptionSize, ETextSize, Caption, Text, TreeView } from "@sberbusiness/triplex-next";
+import "./KeyboardNavigation.less";
+
+interface INodeData {
+    id: string;
+    label: string;
+    children?: INodeData[];
+}
+
+const nodes: INodeData[] = [
+    {
+        id: "folder-1",
+        label: "Folder text",
+        children: [
+            { id: "file-1-1", label: "File text" },
+            { id: "file-1-2", label: "File text" },
+        ],
+    },
+    {
+        id: "folder-2",
+        label: "Folder text",
+        children: [{ id: "file-2-1", label: "File text" }],
+    },
+];
+
+interface ITreeNodeProps {
+    node: INodeData;
+}
+
+const TreeNode = ({ node }: ITreeNodeProps) => (
+    // Ветки раскрыты сразу: стрелки спускаются только в раскрытые ноды.
+    <TreeView.Node id={node.id} opened>
+        {({ activeNode, isLastNode }) => (
+            <>
+                <div className={clsx("tree-view-keyboard-example-row", { active: activeNode })}>
+                    <Text size={ETextSize.B1} tag="span">
+                        {node.label}
+                    </Text>
+                    {isLastNode ? (
+                        <Caption size={ECaptionSize.C2} tag="span">
+                            isLastNode
+                        </Caption>
+                    ) : null}
+                </div>
+                {node.children ? (
+                    <TreeView.Group>
+                        {node.children.map((child) => (
+                            <TreeNode key={child.id} node={child} />
+                        ))}
+                    </TreeView.Group>
+                ) : null}
+            </>
+        )}
+    </TreeView.Node>
+);
+
+export const KeyboardNavigation = () => (
+    <div className="tree-view-keyboard-example" style={{ maxWidth: 420 }}>
+        <Caption size={ECaptionSize.C1} tag="p">
+            Поставьте фокус на любой узел и используйте стрелки вверх/вниз.
+        </Caption>
+        <TreeView aria-label="Tree">
+            {nodes.map((node) => (
+                <TreeNode key={node.id} node={node} />
+            ))}
+        </TreeView>
+    </div>
+);
+```
+

package/bundle/guides/codestyle.md

@@ -135,6 +135,9 @@ import { Button } from "../Button";
 - Имена классов — **camelCase**: `styles.secondaryLight`, `styles.iconOnly`.
 - Никаких **inline styles** в компонентах (в stories допустимо для лейаута примеров).
 - **Цвета** — только через CSS-переменные токенов (`var(--triplex-next-...)`). Никаких hex/rgb.
+  В стилях это правильная запись: CSS-переменные — внутренний слой токенов. А в документации
+  (`*-ai.md`, тексты Storybook) токен указывается путём `{Группа}.{Токен}` — см.
+  `docs/ai/CONTEXT.md` → «Дизайн-токены».
 - Runtime CSS-переменные, которые компонент задаёт сам (например через `style` для динамической высоты,
   transform или координат), называй с префиксом `--triplex-next-runtime-...`.
   Они не являются дизайн-токенами и не должны попадать в `src/components/DesignTokens` или generated-файлы.

package/bundle/guides/commits.md

@@ -56,11 +56,14 @@ TRI-21-alert-ai-ready
 `docs/human/release.md`. Прямой push в `release-0` проверяется CI:
 `ci.yml` триггерится на `push: branches: [release-0]`.
 
-**Единственное исключение для агента** — релизный коммит `release-react17`
-(бамп версии + release notes): он тоже пушится в `release-0` напрямую, без
-PR. Прогон CI на него стартует, но дождаться его нельзя — GitHub Release
-создаётся сразу после push. Поэтому исключение компенсируется обязательными
-локальными гейтами (`tsc`, `test-unit`, `build`).
+**Единственное исключение** — релизный коммит (бамп версии + release notes):
+он тоже попадает в `release-0` напрямую, без PR. В еженедельном релизе его
+делает [`release-weekly.yml`](../../.github/workflows/release-weekly.yml),
+при ручном выпуске — skill `release-react17`. Прогон CI на этот коммит
+стартует, но дождаться его нельзя: релиз создаётся сразу после push. Поэтому
+исключение компенсируется гейтами перед пушем — `npm run test-unit`
+и `npm run build` (последний в `prebuild` гоняет `tsc -p tsconfig.build.json`;
+полный `tsc` гейтом быть не может — он даёт давние ошибки в `stories/`).
 
 ---
 
@@ -86,6 +89,24 @@ TRI-21 Alert: AI refactoring + unit-тесты
 - Тело коммита опционально (для сложных изменений).
 - Язык: русский или английский — не смешивать в одном коммите.
 
+**Исключение — релизные коммиты еженедельного релиза.** Их делает
+[`release-weekly.yml`](../../.github/workflows/release-weekly.yml) в GitHub
+Actions, и они идут **без префикса задачи**:
+
+```text
+Подготовка релиза 0.44.0
+Подготовка релиза 1.44.0
+```
+
+Причина техническая: у Actions нет доступа к Linear, номер задачи взять
+неоткуда, а выдумывать его нельзя. Связь с трекером даёт skill `release-auto`
+— он заводит задачу «Релиз 1.Y.0 / 0.Y.0» по итогам прогона и складывает
+туда ссылки на релизы. Коммит машинный, его авторство видно по автору
+(`dudim-ai`), поэтому потеря префикса не мешает разбору истории.
+
+При **ручном** выпуске (`/release`) префикс обязателен, как обычно: там
+задача Linear заводится до начала работы.
+
 ---
 
 ## Когда запускать линтер
@@ -140,7 +161,8 @@ npx prettier --write src/components/Button/Button.tsx
 
 1. делает коммит по конвенциям этого файла (skill `commit-component`);
 2. пушит ветку;
-3. создаёт PR (см. «PR-воркфлоу»);
+3. дожидается PR от workflow `auto-pr.yml` (см. «PR-воркфлоу»; сам
+   `gh pr create` в ветках `TRI-*` не вызывает);
 4. если менялись stories или визуал компонентов — обновляет baseline-скриншоты
    через skill `update-visual-baselines` (CI-workflow «Update Visual
    Snapshots» + чистка orphan-скриншотов);
@@ -161,9 +183,9 @@ npx prettier --write src/components/Button/Button.tsx
 
 ## GitHub-операции от аккаунта бота
 
-Автоматические GitHub-операции (создание PR, комментарии в PR, запуск
-workflow, авторство коммитов автофинала) выполняются от отдельного
-machine-аккаунта, если у разработчика задан его токен:
+Автоматические GitHub-операции (комментарии в PR, запуск workflow,
+авторство коммитов автофинала) выполняются от отдельного machine-аккаунта,
+если у разработчика задан его токен:
 
 ```bash
 # fine-grained PAT бота: contents:write, pull-requests:write, actions:write
@@ -171,11 +193,18 @@ export TRIPLEX_BOT_GH_TOKEN=...   # в ~/.zshenv (не ~/.zshrc — агент
                                   # в неинтерактивном shell), НЕ в репозитории
 ```
 
+Тот же PAT хранится как repository secret `DUDIM_AI_GH_TOKEN` — его
+использует workflow `auto-pr.yml`, который создаёт PR для веток `TRI-*`
+(см. «PR-воркфлоу»). Благодаря этому автор PR один и тот же независимо от
+того, где шла сессия агента — локально или в облаке. При ротации PAT
+обнови оба места: `~/.zshenv` и secret
+(`gh secret set DUDIM_AI_GH_TOKEN --body "$TRIPLEX_BOT_GH_TOKEN"`).
+
 **Паттерн для агентов** — в начале Bash-вызова с командами `gh`:
 
 ```bash
 if [ -n "$TRIPLEX_BOT_GH_TOKEN" ]; then export GH_TOKEN="$TRIPLEX_BOT_GH_TOKEN"; fi
-gh pr create ...   # выполнится от бота; без токена — от разработчика (fallback)
+gh pr comment ...  # выполнится от бота; без токена — от разработчика (fallback)
 ```
 
 **Авторство коммитов автофинала** (identity бота выводится из токена,
@@ -217,32 +246,83 @@ fi
   permitted for this session type / through this proxy» (у fine-grained
   PAT было бы «…by personal access token»).
 
-Что прокси **разрешает** из облака: push в ветки, создание и мерж PR,
-комментарии, чтение Actions, диспатч нерелизных workflow (например,
-`visual-update.yml` — подтверждено прогонами). Что **запрещает** (зонд
-TRI-117, 2026-08-14): создание релизов, диспатч `release.yml`,
-`repository_dispatch`, создание, push и удаление тегов, удаление веток —
-блокируется публикация релизов любым маршрутом. Поэтому публикация релизов из
-облака невозможна — облачный прогон готовит релиз и передаёт публикацию
-человеку (см. `.agents/skills/release-auto/SKILL.md`). Диагностический
-зонд права на диспатч: POST на
-`actions/workflows/release.yml/dispatches` с несуществующим `ref` —
-`422 No ref found` означает «право есть», `403` — «нет».
+Что доступно из облака — проверено зондами TRI-117 (2026-08-14) и TRI-119
+(2026-08-21):
+
+| Операция | Из облака |
+|---|---|
+| `git push` ветки, включая защищённый `main` | ✅ |
+| Создание и мерж PR, комментарии | ✅ |
+| Чтение REST и Actions | ✅ |
+| Диспатч нерелизных workflow (`visual-update.yml`) | ✅ |
+| `git push` тега | ❌ `RPC failed; HTTP 403` |
+| `POST /git/refs`, `PATCH /git/refs/heads/*` | ❌ |
+| `gh release create` | ❌ |
+| `gh workflow run release.yml`, `repository_dispatch` | ❌ |
+| Удаление веток и тегов | ❌ |
+
+Отказы приходят с текстом `Write access to this GitHub API path is not
+permitted through this proxy` — это ограничение прокси, а не прав токена
+и не настроек репозитория. Менять branch protection бесполезно.
+
+**Следствие для релиза:** выпустить его из облачной сессии нельзя ни одним
+маршрутом. Поэтому механика релиза живёт в GitHub Actions
+(`.github/workflows/release-weekly.yml`), расписание держит сам GitHub, а
+за облачной routine остаётся отчёт — см.
+`.agents/skills/release-auto/SKILL.md`.
 
 ---
 
 ## PR-воркфлоу
 
-**Работа по задаче Linear:** после коммита агент сам пушит ветку и создаёт PR:
+**Работа по задаче Linear:** PR для веток `TRI-*` создаёт workflow
+`auto-pr.yml` (триггер `on: push`) от аккаунта бота — secret
+`DUDIM_AI_GH_TOKEN`. Так автор PR не зависит от среды сессии: локальный
+`gh pr create` шёл бы от PAT бота, а облачный — от GitHub App `claude`
+(прокси подменяет авторизацию, см. «Облачные сессии»). Агент **не вызывает
+`gh pr create` в ветках `TRI-*`** — иначе облачная сессия успеет создать
+PR от `claude[bot]` раньше workflow.
+
+Финальный коммит — это и есть источник PR: заголовок берётся из первой
+строки (`TRI-XXX Краткое описание`), описание — из тела коммита. Поэтому
+в автофинале тело коммита обязательно и содержит описание PR
+(«Что сделано» / «Как проверить»).
 
 ```bash
 git push -u origin TRI-XXX-feature-name
-gh pr create \
-  --title "TRI-XXX Краткое описание" \
-  --body "## Что сделано\n- ...\n\n## Как проверить\n- ..."
+# PR создаст auto-pr.yml через ~20–60 с; дождись его появления:
+for i in $(seq 1 12); do
+  pr_url=$(gh pr list --head "TRI-XXX-feature-name" --base main --state open \
+    --json url --jq '.[0].url // empty') && [ -n "$pr_url" ] && break
+  sleep 10
+done
+echo "${pr_url:-PR не появился}"
 ```
 
-После создания PR финал продолжается автоматически: skill
+Если PR не появился за ~2 минуты — проверь прогон workflow именно для
+текущего коммита (не по ветке: `--limit 1` по ветке может показать прогон
+предыдущего пуша):
+`gh run list --workflow=auto-pr.yml --commit $(git rev-parse HEAD) --limit 1`.
+Дальше по статусу:
+
+- `queued` / `in_progress` — прогон ещё идёт, продолжай ждать;
+- `completed` + `success` без PR — сработал guard (маркер `[no-pr]`,
+  subject не по формату `TRI-XXX ...` или ветка без новых коммитов
+  относительно `main`) — штатное завершение без PR, fallback не нужен;
+- `completed` + `failure` или прогона нет (например, протух secret) —
+  fallback.
+Fallback — прежняя схема: `gh pr create` с паттерном bot-токена из
+раздела выше.
+Fallback безопасен: раз workflow PR не создал, гонки нет. В облачной
+сессии fallback-PR будет от `claude[bot]` (прокси подменит PAT — см.
+«Облачные сессии») — это осознанная деградация, лучше PR от app'а, чем
+отсутствие PR.
+
+Обход автосоздания (WIP-пуш ветки `TRI-*` без PR): добавь маркер `[no-pr]`
+в первую строку HEAD-коммита. Коммиты не по формату `TRI-XXX ...`
+(например, `chore: ...`) PR также не создают.
+
+После появления PR финал продолжается автоматически: skill
 `update-visual-baselines` (если менялись stories/визуал) и skill
 `finish-task` — комментарий-резюме в задаче Linear и проверка линковки PR
 (GitHub-интеграция Linear подхватит PR по `TRI-XXX` в имени ветки).