From 21eb8331d22759cd7e63034dfbbc724c688fa6e1 Mon Sep 17 00:00:00 2001
From: Lacky1234union <rogachevegorushka@yandex.ru>
Date: Mon, 12 Oct 2026 18:20:04 +0300
Subject: [PATCH 1/2] =?UTF-8?q?docs:=20=D1=88=D0=BF=D0=B0=D1=80=D0=B3?=
 =?UTF-8?q?=D0=B0=D0=BB=D0=BA=D0=B0=20=D0=BF=D0=BE=20SourceCraft=20API,=20?=
 =?UTF-8?q?=D0=B7=D0=B0=D0=B3=D1=80=D1=83=D0=B7=D0=BA=D0=B0=20.env=20?=
 =?UTF-8?q?=D0=B2=20=D0=BD=D0=B0=D1=87=D0=B0=D0=BB=D0=B5=20=D1=81=D0=B5?=
 =?UTF-8?q?=D1=81=D1=81=D0=B8=D0=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refs #1

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CLAUDE.md                   | 12 +++++++
 docs/dev/SOURCECRAFT_API.md | 69 +++++++++++++++++++++++++++++++++++++
 docs/dev/WORKFLOW.md        |  2 +-
 3 files changed, 82 insertions(+), 1 deletion(-)
 create mode 100644 docs/dev/SOURCECRAFT_API.md

diff --git a/CLAUDE.md b/CLAUDE.md
index 5de2628..e244e89 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,5 +1,16 @@
 # CLAUDE.md — Руководство для Claude Code
 
+## ⚡ ПЕРВОЕ ДЕЙСТВИЕ В КАЖДОЙ СЕССИИ
+
+```bash
+set -a; . ./.env 2>/dev/null; set +a
+```
+
+`SOURCECRAFT_TOKEN` — токен SourceCraft API (секрет — **в чат не печатать**). Репозиторий:
+[`rogachevegorushka/tgit`](https://sourcecraft.dev/rogachevegorushka/tgit). API → [`docs/dev/SOURCECRAFT_API.md`](docs/dev/SOURCECRAFT_API.md).
+
+---
+
 ## Что мы строим
 
 Telegram-бот (учебный проект НИУ ВШЭ, курс Python): принимает `.py`-файлы, коммитит их в отдельный
@@ -30,6 +41,7 @@ Telegram-бот (учебный проект НИУ ВШЭ, курс Python): п
 | [`docs/QUESTIONS_IDEAS.md`](docs/QUESTIONS_IDEAS.md) | Открытые вопросы, бэклог идей |
 | [`docs/dev/WORKFLOW.md`](docs/dev/WORKFLOW.md) | Регламент: ветки, коммиты, PR, жизненный цикл задачи |
 | [`docs/dev/ISSUE_TEMPLATE.md`](docs/dev/ISSUE_TEMPLATE.md) | Шаблон тела issue |
+| [`docs/dev/SOURCECRAFT_API.md`](docs/dev/SOURCECRAFT_API.md) | SourceCraft API: curl-шпаргалка (issue, метки, PR) |
 
 ---
 
diff --git a/docs/dev/SOURCECRAFT_API.md b/docs/dev/SOURCECRAFT_API.md
new file mode 100644
index 0000000..a3c29ed
--- /dev/null
+++ b/docs/dev/SOURCECRAFT_API.md
@@ -0,0 +1,69 @@
+# SourceCraft API — шпаргалка
+
+Справочник: [методы](https://sourcecraft.dev/portal/docs/en/api-ref/index.md) ·
+[интерактивный](https://api.sourcecraft.tech/docs/index.html) ·
+[swagger.json](https://api.sourcecraft.tech/sourcecraft.swagger.json)
+
+```bash
+set -a; . ./.env; set +a                     # SOURCECRAFT_TOKEN
+R=https://api.sourcecraft.tech/repos/rogachevegorushka/tgit
+H="Authorization: Bearer $SOURCECRAFT_TOKEN"
+J="Content-Type: application/json"
+```
+
+> В CI вместо личного токена — предопределённая переменная `SOURCECRAFT_TOKEN`.
+
+## Подводные камни
+
+- `color` у метки — hex **без** `#` (`"ff7f0e"`), иначе `400 ValidationError`.
+- Ответы-списки кладут элементы в разные ключи: `/issues` → `issues`, `/labels` репо → `items`, метки issue → `labels`.
+- Issue адресуется номером (`issues/1`), метка — slug'ом (`size/0.5` → `size-0-5`).
+- Тело issue — поле `description` (не `body`); тело комментария — `body`.
+- Длинный markdown удобнее собрать в JSON-файл и передать `--data @file.json`.
+
+## Issues
+
+```bash
+# список / одна
+curl -s -H "$H" "$R/issues"
+curl -s -H "$H" "$R/issues/1"
+
+# создать (status_slug: open | inProgress | paused | closed | declined | duplicate)
+curl -s -X POST -H "$H" -H "$J" "$R/issues" --data @issue.json
+# issue.json: {"title": "...", "description": "...", "label_slugs": ["bot","feature","size-1"], "status_slug": "open"}
+
+# обновить (описание, статус, исполнитель)
+curl -s -X PATCH -H "$H" -H "$J" "$R/issues/1" -d '{"status_slug":"closed"}'
+
+# комментарий
+curl -s -X POST -H "$H" -H "$J" "$R/issues/1/comments" -d '{"body":"текст"}'
+
+# метки issue: POST — добавить, PUT — заменить, DELETE — убрать
+curl -s -X POST -H "$H" -H "$J" "$R/issues/1/labels" -d '{"slugs":["ci"]}'
+
+# связь между issue
+curl -s -X POST -H "$H" -H "$J" "$R/issues/2/issue_links" --data @link.json
+```
+
+## Метки репозитория
+
+```bash
+curl -s -H "$H" "$R/labels"
+curl -s -X POST -H "$H" -H "$J" "$R/labels" -d '{"name":"size/1","slug":"size-1","color":"a0a0a0"}'
+```
+
+Заведены: зоны `bot` `ci` `infra` `llm` `docs` · типы `feature` `fix` `refactor` · размеры `size/0.5` `size/1` `size/2`.
+
+## Pull requests
+
+```bash
+# создать PR в dev
+curl -s -X POST -H "$H" -H "$J" "$R/pulls" --data @pr.json
+# pr.json: {"title": "...", "description": "...", "source_branch": "feat/2-x", "target_branch": "dev", "publish": true}
+
+curl -s -H "$H" "$R/pulls/1"
+curl -s -H "$H" "$R/pulls/1/merge-checks"
+
+# мерж (rebase | squash, delete_branch)
+curl -s -X POST -H "$H" -H "$J" "$R/pulls/1/merge" -d '{"delete_branch": true}'
+```
diff --git a/docs/dev/WORKFLOW.md b/docs/dev/WORKFLOW.md
index 5fb871e..fa7f5e7 100644
--- a/docs/dev/WORKFLOW.md
+++ b/docs/dev/WORKFLOW.md
@@ -2,7 +2,7 @@
 
 ## Откуда задачи
 
-- Только из Issues на SourceCraft. Нет issue → завести → потом код.
+- Только из Issues на SourceCraft. Нет issue → завести → потом код. API: [`SOURCECRAFT_API.md`](SOURCECRAFT_API.md).
 - Атрибуты issue: исполнитель, метка зоны (`bot` / `ci` / `infra` / `llm` / `docs`),
   тип (`feature` / `fix` / `refactor` / `docs`), размер (`size/0.5` ≈ 2ч · `size/1` ≈ 4ч · `size/2` ≈ 1д).
 - Тело — по [`ISSUE_TEMPLATE.md`](ISSUE_TEMPLATE.md).

From 47dd849528d60a07e6c3e1933e5b4b6f99ea3b29 Mon Sep 17 00:00:00 2001
From: Lacky1234union <rogachevegorushka@yandex.ru>
Date: Mon, 12 Oct 2026 18:22:22 +0300
Subject: [PATCH 2/2] =?UTF-8?q?docs:=20=D1=80=D0=B5=D1=82=D1=80=D0=B0?=
 =?UTF-8?q?=D0=B8=20curl=20=D0=B4=D0=BB=D1=8F=20=D0=BD=D0=B5=D1=81=D1=82?=
 =?UTF-8?q?=D0=B0=D0=B1=D0=B8=D0=BB=D1=8C=D0=BD=D0=BE=D0=B3=D0=BE=20=D1=81?=
 =?UTF-8?q?=D0=BE=D0=B5=D0=B4=D0=B8=D0=BD=D0=B5=D0=BD=D0=B8=D1=8F=20=D1=81?=
 =?UTF-8?q?=20API?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refs #1

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/dev/SOURCECRAFT_API.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/dev/SOURCECRAFT_API.md b/docs/dev/SOURCECRAFT_API.md
index a3c29ed..000f826 100644
--- a/docs/dev/SOURCECRAFT_API.md
+++ b/docs/dev/SOURCECRAFT_API.md
@@ -8,6 +8,7 @@
 set -a; . ./.env; set +a                     # SOURCECRAFT_TOKEN
 R=https://api.sourcecraft.tech/repos/rogachevegorushka/tgit
 H="Authorization: Bearer $SOURCECRAFT_TOKEN"
+alias curl='curl --retry 4 --retry-all-errors --retry-delay 2'
 J="Content-Type: application/json"
 ```
 
@@ -15,6 +16,7 @@ J="Content-Type: application/json"
 
 ## Подводные камни
 
+- Соединение с `api.sourcecraft.tech` иногда рвётся (`curl: (35)`, пустой ответ) — отсюда `--retry`. Перед повторным POST проверить, не создалась ли сущность.
 - `color` у метки — hex **без** `#` (`"ff7f0e"`), иначе `400 ValidationError`.
 - Ответы-списки кладут элементы в разные ключи: `/issues` → `issues`, `/labels` репо → `items`, метки issue → `labels`.
 - Issue адресуется номером (`issues/1`), метка — slug'ом (`size/0.5` → `size-0-5`).