Initial commit: Hermes skill git-forge-management

references/gitverse-api.md

@@ -0,0 +1,47 @@
+# GitVerse API — рабочие эндпоинты и питфолы (проверено 2026-09-06)
+
+## Ключевой факт: базовый URL
+
+- **API: `https://api.gitverse.ru`** (Gitea-совместимый: `/user/repos`, `/repos/{owner}/{repo}/...`, `/users/{login}`)
+- **НЕ** `https://gitverse.ru/api/v1/...` — этот путь отдаёт HTML (Next.js SPA), а не JSON. Любой curl туда вернёт `<DOCTYPE html>`.
+- API-документация (человекочитаемая, по эндпоинтам): `https://gitverse.ru/docs/developers/public-api` (страница SPA, парсить текст через curl -sL + strip тегов).
+
+## Аутентификация
+
+- Все токены — в `/opt/hermes/.hermes/secrets/git-tokens.env` (source): `GITVERSE_PAT`, `GITEA_TOKEN`, `GITVERSE_LOGIN`, `GITVERSE_API`, `GITEA_API`.
+- `Authorization: Bearer <PAT>` (gitverse) и `Authorization: token <GITEA_TOKEN>` (gitea).
+- Для создания/чтения объектов репо gitverse рекомендован Accept: `application/vnd.gitverse.object+json;version=1` (без него `/user` и `/user/repos` отдают 400).
+
+## Создание репозитория
+
+```bash
+source /opt/hermes/.hermes/secrets/git-tokens.env
+curl -s -X POST "$GITVERSE_API/user/repos" \
+  -H "Authorization: Bearer $GITVERSE_PAT" \
+  -H "Accept: application/vnd.gitverse.object+json;version=1" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"repo-name","description":"...","private":true}'
+```
+
+- HTTP 201 = создан; в ответе `id`, `full_name`, `html_url`, `clone_url`, `default_branch` (у GitVerse — `master` при пустом репо).
+- Поддерживаемые поля тела: `name` (обязательное), `description`, `private`, `auto_init`, `gitignores[]`, `is_template`. НЕ поддерживаются `license_template`, `has_wiki`, `has_issues` (API их игнорирует/ошибается).
+- `auto_init: true` создаёт пустой README — для пуша готовой локальной истории ставить `false`.
+
+## Питфол: реальный логин аккаунта ≠ ожидаемый
+
+- В remote можно заложить `https://estorozhenko:<TOKEN>@gitverse.ru/estorozhenko/openspec-lab.git`, но push упадёт/remote не совпадёт, если фактический логин другой.
+- Реальный владелец виден в ответе API: поле `full_name` = `<реальный-логин>/<repo>` (в нашем случае аккаунт оказался **kpa39l**, не estorozhenko).
+- После создания репо: `git remote set-url origin https://<реальный-логин>:<TOKEN>@gitverse.ru/<реальный-логин>/<repo>.git`, затем `git push -u origin main`.
+- Проверка перед push, если сомневаетесь: `curl -s -H "Authorization: Bearer $TOKEN" https://api.gitverse.ru/user` → `"login"` в JSON.
+- GitVerse может создать дефолтную ветку `master` (пустой репо). Локально `main` — при пуше `-u origin main` ветка создастся, но дефолт останется `master`; менять в настройках репо или оставить как есть.
+
+## Краткая справка по docs
+
+Полезные эндпоинты (Gitea-совместимые, все под api.gitverse.ru):
+- `GET /user` — текущий пользователь (login, id)
+- `GET /user/repos` — список своих репозиториев
+- `POST /user/repos` — создать
+- `PATCH /repos/{owner}/{repo}` — обновить метаданные (в т.ч. mirror)
+- `GET /repos/{owner}/{repo}` — инфо репозитория
+
+Полная навигация по докам: страница `/docs/developers/public-api` содержит ссылки вида `/docs/developers/public-api/<category>/<api-slug>` — категории: repositories, git-database, actions, collaborators, orgs-teams, migration, user-management.