docs: AGENTS.md (gitea issue tracker workflow) + docs/agents/issue-tracker.md

AGENTS.md

@@ -0,0 +1,7 @@
+# AGENTS.md
+
+## Agent skills
+
+- **Issue tracker**: Gitea — `hermes/email-assistant` on https://gitea.nixg.ru.
+  See `docs/agents/issue-tracker.md` for the full workflow (tea CLI `gitea.nixg-full` login / gitea-mcp MCP tools, triage labels, blocking-edge convention).
+- **Domain docs**: single-context — `CONTEXT.md` and `docs/adr/` at repo root if/when they exist.

WALKTHROUGH.md

@@ -497,4 +497,23 @@ mirror-sync `POST $GITEA_API/repos/estorozhenko/email-assistant/mirror-sync` →
   выбор: ставить его или свой клиент поверх imap_connect() (raw socket).
 - Backlog 10 urgent-писем (июль-сентябрь): отправляются по 2/прогон крона в ЛС;
   часть просрочена — решить, пропускать ли (пометить handled).
+
+## 2026-09-16 — сессия закрыта (происшествие: путаница проектов)
+
+Сессия ошибочно начата с выполнения задач **/opt/vesti/TODO.md**: агент неверно
+истолковал запрос «todo пустой?» и открыл чужой TODO (vesti), вместо своего
+(TODO.md email-assistant). Пользователь указал: **сессии email-assistant работают
+только с email-assistant**; задачи vesti живут в /opt/vesti/TODO.md и выполняются
+только по явной команде.
+
+**Проверка (выполнена):** в файлах email-assistant (TODO.md, STATUS.md,
+WALKTHROUGH.md, AGENT.md) задач проекта vesti НЕТ — все упоминания vesti
+технические (VESTI_BOT_TOKEN из /opt/vesti/.env, python /opt/vesti/.venv/bin,
+дефолт канала @dedinit_vesti). Переносить нечего. Файлы email-assistant в этой
+сессии не изменялись.
+
+**Побочный эффект:** в /opt/vesti остались незакоммиченные изменения от
+ошибочной работы (openspec/changes/manual-direction/, extract-post-sources/,
+sources/extract.py, правки web/app.py, web/templates/selected.html, TODO.md
+vesti, bot-флаг vesti на GtS=True) — судьбу решает пользователь.
 - Live-тесты Exchange: пауза ≥45с между подключениями (rate-limit).

docs/agents/issue-tracker.md

@@ -0,0 +1,69 @@
+# Issue Tracker
+
+**Tracker:** Gitea (self-hosted, https://gitea.nixg.ru)
+**Repository:** `hermes/email-assistant`
+**Web UI:** https://gitea.nixg.ru/hermes/email-assistant
+
+This is a custom ("Other") tracker configuration for the Matt Pocock engineering skills (`to-tickets`, `to-spec`, `triage`). Gitea is not natively supported by `/setup-matt-pocock-skills` (which offers GitHub / GitLab / local files), so the workflow is recorded here as freeform prose.
+
+## How to publish issues
+
+Use the **`tea` CLI** (v0.16.0, at `~/.local/bin/tea`) with the login **`gitea.nixg-full`**:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+
+# Create an issue
+tea issues create --login gitea.nixg-full --repo hermes/email-assistant \
+  --title "Ticket title" \
+  --description "Ticket body (use the to-tickets per-ticket template)" \
+  --labels "ready-for-agent"
+
+# List issues
+tea issues list --login gitea.nixg-full --repo hermes/email-assistant -o simple
+
+# Show one issue (with comments)
+tea issues --login gitea.nixg-full --repo hermes/email-assistant 42 --comments
+
+# Add a comment
+tea comment --login gitea.nixg-full --repo hermes/email-assistant 42 "comment"
+
+# Close / reopen
+tea issues close --login gitea.nixg-full --repo hermes/email-assistant 42
+```
+
+**Alternative:** the `gitea` MCP server (gitea-mcp, 72 tools: `create_issue`, `list_issues`, `update_issue`, `add_issue_labels`, ...) is configured in Hermes `mcp_servers.gitea` — it talks to the same instance with the same token. Use whichever is more convenient; prefer MCP tools when you are already in an agent session, `tea` for quick shell checks.
+
+## Repository and credentials
+
+- Instance: `https://gitea.nixg.ru` (API v1.26.2, external VPS 5.129.217.146)
+- Owner/repo: `hermes/email-assistant` (issues enabled: yes)
+- Login (tea): `gitea.nixg-full` — token `hermes-mcp-full` (full: `read:user`, `write:user`, `read:issue`, `write:issue`, `read:repository`, `write:repository`)
+- Token source: `/opt/hermes/.hermes/secrets/git-tokens.env` (`GITEA_NIXG_TOKEN`); also in Hermes `config.yaml` → `mcp_servers.gitea` env `GITEA_TOKEN`.
+- SSH (for git push): `ssh://git@gitea.nixg.ru:2222/hermes/email-assistant.git`
+
+## Triage labels (created)
+
+The five canonical labels are already created in this repo (IDs shown):
+
+| Label | Color | ID |
+|---|---|---|
+| `needs-triage` | `#e11d21` | 1 |
+| `needs-info` | `#fbca04` | 2 |
+| `ready-for-agent` | `#0e8a16` | 3 |
+| `ready-for-human` | `#006b75` | 4 |
+| `wontfix` | `#ffffff` | 5 |
+
+Use `ready-for-agent` for tickets published by `to-tickets` (agent-grabbable by construction, per the skill default).
+
+## Blocking edges
+
+Gitea has no native issue-blocking links in the API used here. Follow the `to-tickets` rule for trackers without native blocking: publish tickets in dependency order (blockers first), and set each ticket's **"Blocked by"** section to the blocking issues' real identifiers (e.g. `#12`, `#13`).
+
+## Scope / local files fallback
+
+If a task is not tied to `hermes/email-assistant` (e.g. infra on another repo), either:
+- create the issue in the matching repo on gitea.nixg.ru (`tea issues create --repo <owner>/<repo>`), or
+- fall back to local markdown under `.scratch/<feature>/issues/` in that project.
+
+Update this file if the tracker repository ever changes.