From a65cb74d88113fdd784e7cff1972a36600ec1c69 Mon Sep 17 00:00:00 2001
From: Dmitriy Dementiev <d.dementiev@concept-software.ru>
Date: Wed, 12 Aug 2026 15:23:16 +0300
Subject: [PATCH] =?UTF-8?q?docs(agents):=20=D0=BE=D0=BF=D0=B8=D1=81=D0=B0?=
 =?UTF-8?q?=D0=BD=D1=8B=20=D0=BE=D0=BF=D0=B5=D1=80=D0=B0=D1=86=D0=B8=D0=B8?=
 =?UTF-8?q?=20=D0=BA=D0=B0=D1=80=D1=82=D1=8B=20wayfinder=20=D0=B2=20Gitea?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Зачем:
  - навык wayfinder ожидает раздел про операции карты в документе трекера, а
    в Gitea 1.27 нет подзадач, поэтому конвенции надо было зафиксировать явно.
- Что:
  - описана принадлежность тикета карте через метку и ссылку в теле, поскольку
    родительских связей в API нет.
  - блокировки заведены на нативные зависимости Gitea, добавлены запросы фронтира.
  - зафиксированы три особенности tea api: путь без ведущего слэша, обязательные
    owner и repo в теле зависимости, нулевой код возврата при HTTP 404.
- Проверка:
  - tea issues list --remote origin --labels wayfinder:map
  - tea api --remote origin repos/ddmitry/local-transcriber/issues/14/dependencies

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 docs/agents/issue-tracker.md | 52 ++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md
index 2c433a2..2c8013e 100644
--- a/docs/agents/issue-tracker.md
+++ b/docs/agents/issue-tracker.md
@@ -64,3 +64,55 @@ tea labels list --remote origin
 
 За пределами рабочего дерева явно указывать репозиторий
 `ddmitry/local-transcriber` и настроенный Gitea login.
+
+## Wayfinding operations
+
+Навык `wayfinder` ведёт карту как issue с меткой `wayfinder:map`, а её тикеты —
+как отдельные issue с метками `wayfinder:research`, `wayfinder:prototype`,
+`wayfinder:grilling` и `wayfinder:task`.
+
+### Принадлежность карте
+
+Gitea 1.27 не имеет подзадач в API: среди эндпоинтов `issues/{index}` есть
+`dependencies` и `blocks`, но родительских связей нет. Поэтому принадлежность
+тикета карте выражается двумя способами сразу: меткой `wayfinder:<тип>` и первой
+строкой тела со ссылкой на карту.
+
+```markdown
+Часть карты: [<заголовок карты>](<url>) (#<номер>)
+```
+
+### Блокировки
+
+Блокировки — нативные зависимости Gitea, они отображаются в интерфейсе. Тикет
+разблокирован, когда закрыты все блокирующие его тикеты.
+
+```powershell
+tea api --remote origin -X POST `
+  repos/ddmitry/local-transcriber/issues/<блокируемый>/dependencies `
+  -d '{"index": <блокирующий>, "owner": "ddmitry", "repo": "local-transcriber"}'
+```
+
+### Запросы фронтира
+
+Фронтир — открытые, разблокированные и никому не назначенные тикеты карты.
+Заявка на тикет — назначение его на себя до начала работы.
+
+```powershell
+tea issues list --remote origin --labels wayfinder:map
+tea issues list --remote origin --labels wayfinder:research,wayfinder:prototype,wayfinder:grilling,wayfinder:task
+tea api --remote origin repos/ddmitry/local-transcriber/issues/<номер>/dependencies
+```
+
+### Особенности `tea api`
+
+Три вещи, на которых легко потерять время:
+
+- **Путь без ведущего слэша.** `repos/{owner}/{repo}/...` работает,
+  `/repos/...` возвращает `404 page not found`. Подстановка `{owner}` и `{repo}`
+  из контекста репозитория при этом не срабатывает — писать владельца и имя явно.
+- **Тело зависимости требует `owner` и `repo`.** Только `{"index": N}` даёт
+  `repository does not exist [id: 0, uid: 0, owner_name: , name: ]`.
+- **Код возврата не отражает HTTP-статус.** `tea api` завершается с нулевым
+  кодом даже на 404, поэтому скрипты должны запрашивать `-i` и разбирать строку
+  `HTTP/...` из stderr, иначе ошибки пройдут незамеченными.