docs: cover private HTTPS build repositories

.research/260824_tz-docs-build-https.md

@@ -0,0 +1,92 @@
+# ТЗ: доки cocoaskills под приватный HTTPS (build_https)
+
+Дата: 2026-08-24. Основание: feat/build-https-broker влита в main
+(be88caa, 9a1f9da, 5381317 поверх 97cfa77), задача борда
+TASK-260824-1dop3s принята ревью. Сьют 1576 passed.
+
+Правки, которые main УЖЕ содержит (переделывать не нужно):
+external-build-repositories.md (секция приватного HTTPS: брокер, три
+источника токена, скоупы, precheck, кроссплатформенный механизм,
+предупреждение про непиненный override), cli.md (группа csk config
+build-https add/login/list/remove + CSK_BUILD_HTTPS_TOKEN /
+CSK_BUILD_HTTPS_HOST), reference.md (поле build_https: грамматика
+скоупов, источники, precedence), CHANGELOG.md (запись в Unreleased).
+
+## 1. README.md: quickstart для приватных репозиториев (обязательно)
+
+Рядом с существующим SSH-блоком, тем же тоном, 6-10 строк:
+- одна фраза: приватный репозиторий сборки работает и по SSH, и по HTTPS;
+- для HTTPS ничего заводить не надо, если человек уже клонирует по HTTPS:
+  csk предложит переиспользовать его собственные креды при первой
+  установке (один Enter);
+- команда для неинтерактивного случая:
+  csk config build-https add gitlab.example.com/portals/infra --token git-credentials
+- строка про CI: CSK_BUILD_HTTPS_TOKEN (+ CSK_BUILD_HTTPS_HOST, если
+  билд-репозитории живут на разных хостах);
+- закрывающая фраза в духе существующей: пакет скилла креды выбрать не
+  может.
+
+## 2. docs/skill-authoring.md §3 (schema v7): транспорт не диктует доступ
+
+Строки ~326-330 говорят только про SSH. Переписать абзац:
+- в build_repositories.*.git допустимы обе формы: git@host:path.git и
+  https://host/path.git;
+- приватный репозиторий в обоих случаях требует явного выбора кредов
+  оператором: скоупы build_ssh и build_https соответственно;
+- выбор транспорта не решает, у кого установка получится: SSH требует
+  ключ, HTTPS требует существующие креды Git или токен;
+- ссылку на docs/external-build-repositories.md сохранить.
+
+ЯВНО упомянуть: HTTPS URL в манифесте обязан нести суффикс .git. Без
+него GitLab отвечает 301, fetch идёт с http.followRedirects=false, и
+установка падает build_repository_source_unavailable. Это требование к
+манифесту; писать там, где авторы пишут URL.
+
+## 3. docs/troubleshooting.md: две новые записи
+
+Формат существующий (симптом, причина, команда).
+
+build_repository_credential_policy_invalid: скоуп выбран, источник
+ничего не дал. Три ветки, по команде на каждую: не установлена
+переменная из token_env; token: keyring без сохранённого токена
+(лечение: csk config build-https login <scope>); token: git-credentials
+без записи у helper'а для хоста (клонировать один раз по HTTPS либо
+login). Текст ошибки называет конкретный случай.
+
+fatal: ... The requested URL returned error: 301: HTTPS URL без
+суффикса .git; fetch не следует редиректам by design. Лечение: добавить
+.git в build_repositories.*.git. Симптом ловится как
+build_repository_source_unavailable, запись должна находиться и по
+этому коду.
+
+Windows-специфика (там же или в записи про login): git credential
+approve рапортует успех, даже когда Windows Credential Manager
+недоступен; csk ловит это перечитыванием и говорит, что делать;
+рецепты: интерактивная сессия либо git config --global
+credential.credentialStore dpapi. Проверено на живой Windows-машине.
+
+## 4. docs/reference.md: матрица установки
+
+Проверить, упоминает ли матрица вариантов установки, что компилируемые
+команды (go-repository-v1) поддерживаются только на macOS и Windows.
+Если нет: добавить строку, что на Linux скилл с такой командой не
+установится независимо от кредов, отказ происходит до старта воркера.
+
+## Ограничения
+
+- Язык каждого файла сохранять, не смешивать внутри файла.
+- docs/prose-style.md обязателен; тире как риторическая связка запрещено
+  в любом языке.
+- Секреты в примерах не показывать; токен нигде не принимается флагом.
+- Каждый пример прогнать на csk из дерева (.venv/bin/csk, НЕ brew) и
+  сверить с фактическим выводом.
+
+## Приёмка
+
+1. Ссылки из README ведут на новые разделы; проверка ссылок зелёная.
+2. Ни одного примера, которого нет в CLI (сверить с
+   .venv/bin/csk config build-https --help).
+3. Автор скилла из одного skill-authoring.md знает про обе формы URL и
+   обязательный .git в HTTPS.
+4. Человек с build_repository_credential_policy_invalid находит свою
+   ветку и команду в troubleshooting.md.

LOGBOOK.md

@@ -122,6 +122,28 @@ last members are routinely mid-exit when the first group signal is sent. The reg
 The failure never reproduced on the fast tier because it is a per-teardown dice roll of roughly one
 in fourteen, and each E2E job performs a handful of teardowns. Re-running the red job turned it
 green, which is the shape a flake has and the shape a broken merge does not.
+## 2026-08-24 - TASK-260824-2rzwqa troubleshooting entries for build_https and reference matrix fix
+
+Added two troubleshooting entries in `docs/troubleshooting.md` following the symptom-cause-remedy format and updated `docs/reference.md` installation matrix:
+
+1. `build_repository_credential_policy_invalid`: documents the three branches (`token_env` with missing env var, `keyring` with no stored token, `git-credentials` with no helper entry) and their resolution commands. Includes the Windows note attributing token verification failure to `csk config build-https login` when Windows Credential Manager is unavailable (`your Git credential helper did not persist the token`), with remedies for interactive sessions and DPAPI (`git config --global credential.credentialStore dpapi`).
+2. `build_repository_source_unavailable / fatal: ... The requested URL returned error: 301`: documents HTTPS URL missing `.git` suffix causing HTTP 301 redirects, `http.followRedirects=false` behavior, and remedy of appending `.git` to `build_repositories.*.git`. Findable by both error codes.
+3. `docs/reference.md`: updated the installation matrix line to state that compiled commands `go-repository-v1` are supported only on macOS and Windows, and on Linux the installer rejects skills with such commands before checking credentials or launching worker processes.
+
+All error strings were verified against `src/csk` source files (`installer.py`, `build_https.py`, `git_admission.py`). Formatting strictly adheres to prose style rules (active voice, no em-dashes or en-dashes, no guillemets, clean list blocks).
+
+## 2026-08-24 - TASK-260824-1d7zbo README HTTPS quickstart for private build repositories
+
+The quickstart section for private build repositories in `README.md` previously documented only SSH credentials. With the merge of `feat/build-https-broker` into `main`, private build repositories are also supported over HTTPS.
+
+A 7-line HTTPS quickstart block was added right next to the SSH block, in matching tone and style:
+- States that private build repositories work over both SSH and HTTPS.
+- Explains that readers cloning over HTTPS need no extra setup: `csk` offers to reuse their Git credentials at first install with one Enter.
+- Documents the non-interactive CLI command: `csk config build-https add gitlab.example.com/portals/infra --token git-credentials`.
+- Documents CI environment variables `CSK_BUILD_HTTPS_TOKEN` and `CSK_BUILD_HTTPS_HOST`.
+- Concludes with the rule that a skill package can never choose credentials (only the operator chooses explicitly).
+
+All commands and environment variables were verified against `.venv/bin/csk config build-https --help`. The block strictly follows the documentation prose style (active voice, no em-dashes, colon introducing code block, no secret values).
 
 ## 2026-08-24 - TASK-260824-2h0vjy a byte pin needs a byte-stable checkout
 
@@ -2720,3 +2742,8 @@ The implemented workflow still has no hosted run because this worktree must
 remain uncommitted/unpushed; branch lookup and hosted-run lookup both returned
 empty. A commit-owning mover must publish the scope and attach two green hosted
 runs before the task can satisfy its hosted acceptance gate.
+
+
+## 2026-08-24 TASK-260824-3gv521: Schema v7 Build Repository Transport Documentation
+
+Updated `docs/skill-authoring.md` section 3 (schema v7) to document support for both `git@host:path.git` and `https://host/path.git` transport forms in `build_repositories.*.git`. Clarified that credential selection is required for private repositories in both cases (`build_ssh` and `build_https` scopes), and that choice of transport does not dictate installation access. Stated explicitly that HTTPS URLs must carry the `.git` suffix to avoid GitLab 301 redirects failing under `http.followRedirects=false` with `build_repository_source_unavailable`. Verified error identifier in `src/csk/git_admission.py` and ran `tests/test_git_admission.py` green (exit 0).

README.md

@@ -150,7 +150,15 @@ csk config build-ssh add gitlab.example.com/portals/infra \
     --agent auto --identity ~/.ssh/work.pub
 ```
 
-Пакет скилла выбрать креды не может: выбор делает только оператор и только явно.
+Приватный репозиторий сборки работает и по SSH, и по HTTPS. Для HTTPS ничего заводить не нужно, если вы уже клонируете по HTTPS: `csk` предложит переиспользовать ваши собственные креды Git при первой установке за один Enter. Для неинтерактивного случая выполните команду:
+
+```bash
+csk config build-https add gitlab.example.com/portals/infra --token git-credentials
+```
+
+В CI задайте переменную `CSK_BUILD_HTTPS_TOKEN` (и `CSK_BUILD_HTTPS_HOST`, если репозитории сборки живут на разных хостах).
+
+Пакет скилла выбрать креды не может: выбор делает только оператор и только явно. Подробности устройства брокеров кредов и скоупов описаны в [`docs/external-build-repositories.md`](docs/external-build-repositories.md).
 
 ## Режимы установки скиллов
 
@@ -303,6 +311,7 @@ csk shell-init                      # Генерирует или устанав
 
 - [`docs/cli.md`](docs/cli.md): справочник команд `csk`, флагов и кодов завершения.
 - [`docs/reference.md`](docs/reference.md): справочник по матрице установки, зависимостям скиллов, манифестам и аудиту безопасности.
+- [`docs/external-build-repositories.md`](docs/external-build-repositories.md): устройство внешних репозиториев сборки, брокеров кредов SSH/HTTPS и моделей доступа.
 - [`ARCHITECTURE.md`](ARCHITECTURE.md): описание внутренней архитектуры, схемы работы конвейера установки, формата хранилищ и модели безопасности.
 - [`SECURITY.md`](SECURITY.md): политика безопасности, границы изоляции и рекомендации по настройке.
 - [`docs/skill-authoring.md`](docs/skill-authoring.md): руководство по структурированию пакетов скиллов, объявлению команд и настройке манифеста `agent-skill.json`.

docs/reference.md

@@ -6,7 +6,7 @@ CocoaSkills является независимой реализацией от
 
 ## Матрица вариантов установки
 
-Установщик поддерживается на платформах macOS, Linux и Windows.
+Установщик поддерживается на платформах macOS, Linux и Windows. Компилируемые команды `go-repository-v1` поддерживаются только на macOS и Windows. На Linux установщик отклоняет скилл с такой командой до проверки учётных данных и до запуска воркера.
 
 ### pipx
 

docs/skill-authoring.md

@@ -325,10 +325,17 @@ build/vendor/                    checked-in modules when non-standard packages a
 
 `build_root` содержит `go.mod`; модули вендорятся (`go mod vendor`), сборка
 идёт без сети. Скомпилированный артефакт никогда не коммитится ни в скилл,
-ни во внешний репозиторий. Приватные SSH-источники требуют явного выбора
-кредов оператором; полный контракт, включая скоупы `build_ssh` в глобальном
-конфиге, описан в `docs/external-build-repositories.md`. `go-repository-v1`
-поддерживается только на macOS и Windows.
+ни во внешний репозиторий. Поле `build_repositories.*.git` принимает обе формы
+адреса: `git@host:path.git` и `https://host/path.git`. Приватный репозиторий
+требует явного выбора учётных данных оператором через скоупы `build_ssh` для SSH
+и `build_https` для HTTPS. Выбор транспорта не определяет доступность установки:
+SSH требует SSH-ключ, HTTPS требует сохранённые учётные данные Git или токен.
+Адрес HTTPS в манифесте обязан содержать суффикс `.git`. Без суффикса `.git`
+сервис GitLab отвечает 301, fetch выполняется с `http.followRedirects=false`, и
+установка завершается ошибкой `build_repository_source_unavailable`. Полный
+контракт работы с внешними репозиториями описан в
+`docs/external-build-repositories.md`. `go-repository-v1` поддерживается только
+на macOS и Windows.
 
 ### Схема v8: корни first-party модулей и политика выполнения script-команд