s-clikit 0.1.0__tar.gz

s_clikit-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+# E1.3: приватные local-оверрайды конфига (рядом с project-конфигом) — не в git
+*.local.toml
+.env

s_clikit-0.1.0/AGENTS.md

@@ -0,0 +1,38 @@
+# AGENTS.md — clikit
+
+> Контекст для AI-ассистентов (Claude Code, ChatGPT, Cursor и т.п.), работающих
+> над этим проектом.
+
+## Что это
+
+CLI-методика поверх typer: command_kit, 4-слойный config, SecretStore, scaffold; цель — реестр подключённых адаптеров проекта + команды onboard/health/list поверх них
+
+## Atlas
+
+Проект зарегистрирован в Atlas-БД (NP-005). Карточка:
+
+```sh
+atlas projects get clikit
+```
+
+Любые изменения метаданных (приоритет, статус, теги) — через atlas CLI:
+
+- `atlas projects update clikit --priority P0` — поменять приоритет
+- `atlas add-tags clikit -t domain:<slug>` — добавить тег
+- `atlas projects move clikit --to-type <type>` — конвертировать тип
+
+## Тип / Статус (на момент создания)
+
+- type=`shared-infrastructure`, status=`experiment`, priority=`P0`
+
+## Правила работы
+
+- Все исходные тексты, документы, код проекта — в этом репо.
+- Чувствительные данные (`.env`, токены, ключи) — игнорируются `.gitignore`.
+- AI-ассистенту разрешено: читать, генерировать, редактировать в этом репо.
+
+## Канонические команды
+
+- `atlas projects get clikit` — карточка проекта
+- `atlas pm-tasks list --project clikit` — задачи проекта (когда W7
+  волна будет реализована)

s_clikit-0.1.0/BACKLOG.md

@@ -0,0 +1,110 @@
+# BACKLOG — CLIkit
+
+Бэклог расширений ядра. Приоритезирован по **тому, чего реально не хватило первому
+потребителю** — `downloader`-CLI (скачивание ассетов из сервиса с публичным
+weblink-API), который вынужден был переизобрести загрузочный слой руками. Каждый
+пункт — кандидат вынести из доменного навыка в переиспользуемое ядро, чтобы
+следующий «качающий» CLI собирался так же за ~10 строк.
+
+Статус ядра v0.1.0: транспорт/retry, config/слои, session/keyring, output, errors,
+command-kit, paths, scaffold — **есть**. Загрузка файлов и устойчивость к обрыву —
+**нет** (первый потребитель написал свой resumable-загрузчик + манифест прогресса).
+
+---
+
+## P1 — Resumable HTTP-Range загрузка + checkpoint/manifest
+
+**Зачем.** Потребитель сам реализовал докачку (`.part`-файл, `Range: bytes=N-`,
+обработка 200/206/416, ретраи с пере-резолвом хоста) и манифест прогресса
+(завершённые единицы пропускаются при рестарте, ошибка одного файла не валит
+батч). Это чистый инфраструктурный код без доменной специфики — должен быть в ядре.
+
+**Что дать в API (черновик).**
+- `clikit.download.download_file(client, url, dest, *, on_progress, retries)` —
+  resumable GET через `httpx`: `.part` + Range, корректная обработка
+  `200`/`206`/`416`, валидация полноты по `Content-Range`, ретраи с backoff.
+- `clikit.download.Manifest(dir)` — checkpoint-стор завершённых единиц:
+  `is_done(key)` / `mark(key, result)` / `summary()`. Атомарная запись через
+  существующий `paths.atomic_write_text`.
+- Переиспользовать `RetryPolicy`/`DEFAULT_RETRY` для пауз между попытками.
+
+**Заметки реализации.** `trust_env=False` по умолчанию (урок: токены ссылок бывают
+привязаны к IP — прокси ломает путь). Хост можно пере-резолвить коллбэком
+(signed-token протухает) — параметризовать `url_provider`.
+
+## P2 — Параллельный сегмент/чанк-загрузчик
+
+**Зачем.** Самый ценный трюк потребителя: качать сегменты (напр. `.ts` HLS) в
+`ThreadPoolExecutor` → склейка → постобработка, что дало **×14** к скорости на
+стриминговом источнике (одиночный поток ~0.5 МБ/с, плато ~6.8 МБ/с на ~48 потоках).
+Параллельный «скачать список URL → собрать» — общий примитив (HLS-сегменты,
+многочастные файлы, батч-ассеты).
+
+**Что дать в API.**
+- `clikit.download.fetch_segments(client, urls, dest_dir, *, jobs, retries) -> list[Path]`
+  — параллельная загрузка с пер-сегментными ретраями, детерминированный порядок
+  имён (`{i:06d}`), `all-or-nothing`.
+- Опц. `concat(parts, dest)` — побайтная склейка (сырьём, как TS-сегменты).
+- Настраиваемые `httpx.Limits(max_connections=jobs+N)`.
+
+**Граница.** Постобработка (напр. ffmpeg-конвертация) — **доменная**, в ядро НЕ
+тащим. Ядро отдаёт собранный файл, конвертацию делает навык.
+
+## P3 — Опциональная база SQLite-стора (`clikit[store]`)
+
+**Зачем.** Потребитель завёл свой sqlite-стор (сущности/теги/ссылки + `kv` +
+сессионные куки). Часто повторяющийся паттерн: «локальный каталог сущностей +
+key-value + сессионные куки». Минимальный helper снимет бойлерплейт
+`connect`/`executescript`/`row_factory`.
+
+**Что дать в API (узко, без ORM).**
+- `clikit.store.KVStore(path)` — типизированный key-value на sqlite (`get`/`set`/
+  `get_json`/`set_json`), путь по умолчанию из `AppPaths(brand).cache_dir`.
+- Опц. `Table`-helper для простого upsert/search по dict-схеме — **без** попытки
+  стать ORM (доменные таблицы остаются в навыке).
+
+**Граница.** Доменная схема и бизнес-логика — в навыке. В ядро — только generic
+KV + cookie-jar persistence.
+
+## P4 — browser-warm хелпер (`clikit[browser]`, playwright)
+
+**Зачем.** Паттерн «логин/прогрев в реальном браузере (playwright, `channel=chrome`)
+→ вытащить cookies/токен → дальше httpx напрямую» повторяется в разных навыках
+(прогрев медиа для транскода, логин за антиботом, операции через REST после
+браузерного логина). Достоин общего хелпера.
+
+**Что дать в API (за extra, чтобы playwright не тянулся в каждый CLI).**
+- `clikit.browser.warm_context(url, *, visible, channel="chrome") -> (cookies, ...)`
+  — поднять persistent context, дойти до целевого URL, отдать cookies/storage.
+- `clikit.browser.cookies_to_httpx(cookies)` — мост в `httpx.Client`/заголовок
+  `Cookie`.
+- Лениво импортировать playwright; без extra — понятная ошибка «поставь
+  clikit[browser]».
+
+**Граница.** Хелпер тонкий; тяжёлую логику обхода антибота оставляем
+специализированным навыкам.
+
+## P5 — Scaffold «CLI за 10 строк» (расширение)
+
+`clikit.scaffold` уже генерит скелет (`rest-token`/`none`). Расширения:
+- Транспорт-шаблон `downloader` — CLI вокруг P1/P2 (источник → листинг → resumable
+  download + manifest), чтобы «качающий» навык скаффолдился сразу.
+- Шаблон с `AppConfig`-подклассом + `make_schema_command` из коробки.
+- `clikit new <name> --transport downloader` в CLI-обёртке.
+
+## P6 — Migration-guide для существующих CLI-навыков
+
+Документ-методичка «как мигрировать самописный CLI на CLIkit» (что заменить:
+retry→transport+stamina, свои куки→session/config, `--json`→output, `~/.<app>`→
+paths, Click→command-kit). Обобщить чек-лист «оставить доменным vs вынести в ядро»
+как переиспользуемый шаблон для навыков со своим транспортом/выводом поверх REST.
+
+---
+
+## Принцип границы (ядро vs домен)
+
+Выносим в CLIkit — **generic, без знания конкретного сервиса**: транспорт, retry,
+resumable/parallel загрузка, config-слои, секреты, вывод, пути, scaffold.
+Оставляем в навыке — **доменное**: парсинг конкретного сайта/API, бизнес-схема
+стора, постобработка (конвертация), специфика антибота.
+Тест на вынос: «понадобится ли это второму, не связанному с первым, CLI?».

s_clikit-0.1.0/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+Все значимые изменения CLIkit. Формат — по [Keep a Changelog](https://keepachangelog.com/ru/),
+версионирование — [SemVer](https://semver.org/lang/ru/). Релизы помечаются git-тегами
+`vX.Y.Z` (см. `PUBLISH.md`); dev ведётся в ветках.
+
+## [0.1.0] — 2026-06-18
+
+Первый публикуемый релиз. **Ядро стандарт-библиотеки построения CLI**, извлечённое
+из skills-hub CLI как переиспользуемый слой. Новый CLI-навык собирается за ~10 строк,
+а внутренности построены на зрелых внешних библиотеках — публичный API при этом
+остаётся стабильным контрактом (расширяется, не ломается).
+
+### Что внутри (публичный API — `clikit.__all__`)
+
+**Транспорт (`clikit.transport`)**
+- `HttpClient` — асинхронный REST-клиент поверх `httpx.AsyncClient`: ретраи по
+  `RetryPolicy`, auto-refresh токена при 401 (вне бюджета ретраев), `trust_env=False`
+  по умолчанию (CLI ходит к backend напрямую, минуя системный прокси), внедряемый
+  `http_client` для тестов.
+- `ApiError` — ошибка не-2xx с разобранным FastAPI-конвертом `{"detail": ...}`
+  (dict → `code`/`message`/`details`; str → `message`; list → 422-валидация);
+  машинные `status_code`/`code`/`message`/`details` доступны программно.
+- `RefreshCallback` — тип async-коллбэка обновления токена.
+
+**Политика повторов (`clikit.retry`)**
+- `RetryPolicy` — декларативная политика: ретраебельные статусы (429/5xx),
+  transport-исключения, backoff-таблица + jitter. Применение переведено на
+  [stamina](https://github.com/hynek/stamina) (экспонента + jitter + инструментация),
+  сама политика остаётся декларативным конфигом.
+- `DEFAULT_RETRY` — типовая REST-политика (429/5xx + transport-ошибки, 3 шага).
+
+**Конфигурация (`clikit.config`)**
+- `AppConfig` — база на `pydantic_settings.BaseSettings` (типизация + валидация
+  fail-fast + чтение из окружения). Подклассы добавляют typed-поля наследованием.
+- Слои значений (низ→верх приоритета, **per-key мерж**):
+  `defaults < global(config_dir) < project(.<brand>.toml|.<brand>/config.toml,
+  найден вверх до .git) < local(*.local.toml) < ENV({BRAND}_<FIELD>) < init-kwargs`.
+- `discover_project_config(brand, start)` — подъём от cwd до маркера `.git`.
+- `interpolate_env` — резолв `${VAR}` / `${VAR:-default}` при load (секрет не в git);
+  `$(...)` и голый `$VAR` намеренно не подставляются (поверхность атаки).
+- `load_dotenv_file` — best-effort `.env`-loader (env > .env, не перезаписывает).
+- `McpServer` — единая форма с E6-манифестом навыка (`transport`/`command`/`args`/
+  `env`/`url`/`headers`/`enabled`); `AppConfig.mcp: dict[str, McpServer]`.
+- `AppConfig.json_schema()` — JSON Schema модели для `$schema` в редакторе.
+
+**Хранилище секретов (`clikit.session`)**
+- `SecretStore(brand, profile)` — пара токенов (access/refresh): keyring с прозрачным
+  file-fallback (`tokens.toml`, chmod 600). Fallback закрывает Windows Credential
+  Manager limit (~2560 байт → длинный JWT даёт `CredWrite WinError 1783`).
+  Порядок чтения: env → keyring → файл.
+
+**Вывод (`clikit.output`)**
+- `init_output_mode` / `is_json` / `console` / `emit_data` / `emit_message` /
+  `emit_error` — унифицированный контракт text|json. **Дефолт — json** (для
+  AI-агентов и скриптинга); человек переключается `--text`/`--plain`, env
+  `{BRAND}_OUTPUT=text` или `output_format` в конфиге. Данные в stdout (JSON Lines),
+  сообщения/ошибки в stderr.
+
+**Карта путей (`clikit.paths`)**
+- `AppPaths(brand)` — нативные пути состояния по ОС через
+  [platformdirs](https://github.com/tox-dev/platformdirs) (`config_dir`/`cache_dir`/
+  `sessions_dir`/`locks_dir`); ENV-override `{BRAND}_HOME`.
+- `atomic_write_text` (tmp + `os.replace`), `chmod_600` (POSIX best-effort),
+  `slugify` (детерминированный slug `[a-z0-9._-]`).
+
+**Ошибки (`clikit.errors`)**
+- `CliError` (база: `code`/`message`/`exit_code`) + доменные подклассы
+  `AuthRequired`, `SessionExpired`, `RateLimited` (с `retry_after`),
+  `NotImplementedYet`, `ValidationError`.
+
+**Command-kit (`clikit.command_kit`)**
+- `build_root_app(brand, version, help, status_data, whoami_data)` — root
+  `typer.Typer` с глобальным callback (`--json`/`--text`/`--profile`/`--version`)
+  и базовыми командами `version` + опц. `status`/`whoami`.
+- `command` / `async_command` — декораторы с единым перехватом ошибок:
+  `CliError`/`ApiError` → `emit_error` + `typer.Exit`; `typer.Exit`/`Abort`
+  пропускаются насквозь; в async — `RuntimeError` → короткий `RUNTIME`-emit.
+- `gated(app, permission, has_permission)` — условная регистрация команды по праву.
+- `make_schema_command(MyConfig)` — команда экспорта JSON Schema конфига.
+
+**Scaffold (`clikit.scaffold`)**
+- `scaffold_cli(name, transport, target_dir)` — генерация скелета нового CLI
+  (`<pkg>/cli.py` + `pyproject.toml` + `README.md`), «CLI за ~10 строк».
+  Транспорты: `rest-token` (пример с `HttpClient`) | `none`.
+
+### Зрелые зависимости
+
+`typer`, `httpx`, `rich`, `tomli-w`, `keyring`, `stamina`, `platformdirs`,
+`pydantic-settings`. Опционально: `socks` (`httpx[socks]`).
+
+### Покрытие
+
+154+ теста (pytest + respx), ruff-линт. Запуск:
+`.venv/Scripts/python -m pytest -q` / `.venv/Scripts/python -m ruff check clikit`.
+
+[0.1.0]: https://gitlab.com/cemon345rus/clikit/-/tags/v0.1.0

s_clikit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

s_clikit-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: s-clikit
+Version: 0.1.0
+Summary: Стандартная библиотека построения CLI: transport+retry, config+профили, session(keyring+fallback), output-контракт, errors, command-kit, локальные сессии.
+Author: Dmitry
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28
+Requires-Dist: keyring>=25.0
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: rich>=13.9
+Requires-Dist: s-librarykit
+Requires-Dist: stamina>=24.3
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: typer>=0.15
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: socks
+Requires-Dist: httpx[socks]>=0.28; extra == 'socks'
+Description-Content-Type: text/markdown
+
+# clikit
+
+Стандартная библиотека построения CLI: transport+retry, config+профили,
+session (keyring+file-fallback), output-контракт, errors, command-kit,
+локальные сессии (карта путей). Извлечена из skills-hub CLI как переиспользуемое
+ядро. Новый CLI собирается за ~10 строк.
+
+## Зрелые зависимости (E1.1)
+
+Внутренности построены на проверенных библиотеках (публичный API при этом
+сохранён — контракт не ломается, только расширяется):
+
+- **[stamina](https://github.com/hynek/stamina)** — движок повторов транспорта
+  (экспоненциальный backoff + jitter + лимиты, инструментация). `RetryPolicy` /
+  `DEFAULT_RETRY` остаются декларативным конфигом, их применение переведено на
+  stamina.
+- **[platformdirs](https://github.com/tox-dev/platformdirs)** — нативные пути по
+  ОС для состояния CLI (`%APPDATA%` win / `~/Library` mac / `~/.config` linux).
+  `AppPaths(brand)`: `config_dir`→`user_config_dir`, `cache_dir`→`user_cache_dir`,
+  `sessions`/`locks`→`user_data_dir`. ENV-override `{BRAND}_HOME` перебивает.
+- **[pydantic-settings](https://github.com/pydantic/pydantic-settings)** —
+  `AppConfig` на `BaseSettings`: типизация + валидация (fail-fast) + чтение из
+  окружения. Приоритет источников: init-kwargs > env `{BRAND}_<FIELD>` > слои
+  файлов. Подклассы добавляют typed-поля обычным наследованием.
+
+## Слои конфига: global + project + local (E1.3)
+
+`AppConfig.load(brand)` собирает значения по слоям (низ→верх приоритета),
+**per-key мерж** (верхний слой переопределяет ТОЛЬКО заданные ключи, не
+заменяет объект целиком):
+
+```
+defaults(модель) < global(config_dir/config.toml)
+    < project(.<brand>.toml | .<brand>/config.toml — найден ВВЕРХ от cwd до .git)
+    < local(*.local.toml рядом с project, gitignored)
+    < ENV({BRAND}_<FIELD>) < init-kwargs
+```
+
+- **project-discovery**: подъём от cwd вверх до маркера `.git` (не выходя за
+  границу проекта); ищется `.<brand>.toml` в корне ИЛИ `.<brand>/config.toml`.
+  Это даёт «конфиг рядом с проектом» — библиотека ложится в каждый репозиторий.
+- **local-оверрайд**: `.<brand>.local.toml` (или `.<brand>/config.local.toml`) —
+  приватные правки поверх командного project-конфига (добавлен в `.gitignore`).
+- Профили (`{BRAND}_PROFILE` → `profiles/<p>/`) сохранены на уровне global.
+- `load(path=...)` читает ЕДИНИЧНЫЙ файл (без discovery/слоёв) — обратная
+  совместимость.
+- `discover_project_config(brand, start=cwd)` доступен публично.
+
+### env-интерполяция секретов (E1.3)
+
+Строковые значения резолвятся из окружения при `load` (секрет не лежит в git):
+
+```toml
+api_token = "${ACME_TOKEN}"               # из env ACME_TOKEN
+base_url  = "${ACME_HOST:-http://localhost:8000}"  # с дефолтом (bash ${VAR:-def})
+```
+
+Поддержаны `${VAR}` и `${VAR:-default}`. Подстановка команд `$(...)` **не**
+поддержана (поверхность атаки); голый `$VAR` без скобок не подставляется.
+Заряжать env можно `.env`-loader'ом (`load_dotenv_file`) или keyring (`SecretStore`).
+
+### MCP-секция (E1.3)
+
+`AppConfig.mcp: dict[str, McpServer]` — единая форма с E6-манифестом навыка
+(`transport`/`command`/`args`/`env`/`url`/`headers`/`enabled`), чтобы install
+сервера навыка был прямым mapping. Имена серверов — через дефис (не `_`).
+
+```toml
+[mcp.skills-hub]
+transport = "stdio"            # stdio | sse | http
+command = "skills-hub-mcp"
+args = ["--stdio"]
+env = { TOKEN = "${SH_TOKEN}" }
+
+[mcp.remote-api]
+transport = "http"
+url = "https://mcp.example.com"
+headers = { Authorization = "Bearer ${MCP_TOKEN}" }
+```
+
+### `$schema` для редактора (E1.3)
+
+`AppConfig.json_schema()` (или подкласса) отдаёт JSON Schema модели
+(`model_json_schema`). Команда для CLI — `make_schema_command(MyConfig)`:
+
+```python
+from clikit import make_schema_command, AppConfig
+app.command(name="schema")(make_schema_command(MyConfig))   # `acme schema` печатает схему
+```
+
+Сгенерированную схему публикуют как файл и подключают в редакторе. TOML остаётся
+форматом конфига; для VS Code/JetBrains схему ассоциируют с файлом конфига через
+настройки редактора (Taplo/`tombi` для TOML) либо через `"$schema"`, если перейти
+на JSONC.
+
+## `--json` по умолчанию (E1.1)
+
+Дефолтный режим вывода — **json** (для AI-агентов и скриптинга): без флагов
+команда отдаёт машинный JSON Lines в stdout. Человек переключается в
+человеко-читаемый режим:
+
+- флагом `--text` / `--plain` (форсит text);
+- env `{BRAND}_OUTPUT=text`;
+- в настройках `config.toml` → `output_format = "text"`.
+
+`--json` форсит json (перебивает `--text`, если переданы оба). Полный приоритет
+`init_output_mode`: `json_flag=True` > явный text-сигнал (`text_flag=True` или
+`json_flag=False`) > env `{BRAND}_OUTPUT` > `config_format` > `json` (дефолт).
+
+## Быстрый старт
+
+```python
+from clikit import build_root_app, command, HttpClient, AppConfig, emit_data
+
+app = build_root_app(brand="acme", help="ACME CLI")  # +--json/--text/--profile/--version
+
+@app.command()
+@command
+def items():
+    cfg = AppConfig.load("acme")
+    client = HttpClient(cfg.base_url, access_token=...)
+    emit_data(..., text_renderer=...)
+```
+
+Скаффолд нового CLI: `clikit new <name>` (см. `clikit.scaffold`).
+
+## Публичный API
+
+`clikit.__all__`: `CliError`, `AuthRequired`, `SessionExpired`, `RateLimited`,
+`NotImplementedYet`, `ValidationError`, `RetryPolicy`, `DEFAULT_RETRY`,
+`init_output_mode`, `is_json`, `console`, `emit_data`, `emit_message`,
+`emit_error`, `HttpClient`, `ApiError`, `RefreshCallback`, `AppConfig`,
+`McpServer`, `load_dotenv_file`, `interpolate_env`, `discover_project_config`,
+`SecretStore`, `AppPaths`, `atomic_write_text`, `chmod_600`, `slugify`,
+`build_root_app`, `command`, `async_command`, `gated`, `make_schema_command`,
+`scaffold_cli`.
+
+## Разработка
+
+```bash
+.venv/Scripts/python -m pytest -q          # тесты
+.venv/Scripts/python -m ruff check clikit   # линт
+```

s_clikit-0.1.0/PUBLISH.md

@@ -0,0 +1,112 @@
+# PUBLISH — публикация CLIkit и потребление в CLI-навыках
+
+CLIkit публикуется как **git-зависимость** (без PyPI): любой CLI-навык тянет её
+напрямую из GitLab по тегу. Версионирование — git-тегами `vX.Y.Z`; разработка —
+в ветках. Релиз = коммит на `main` + аннотированный тег + push.
+
+> Дисциплина (см. глобальный CLAUDE.md): **git первый, тег второй, потребление
+> третьим.** Никакой публикации из незакоммиченного дерева. Перед тегом — чистый
+> `git status` и зелёные тесты/линт.
+
+## 0. Предполётная проверка
+
+```bash
+cd <path-to-clikit>                         # корень репозитория clikit
+.venv/Scripts/python -m pytest -q          # все тесты зелёные
+.venv/Scripts/python -m ruff check clikit   # линт чист
+git status --short                          # рабочее дерево чистое
+git log -1 --oneline                        # HEAD на нужном коммите
+```
+
+Версия в `pyproject.toml` (`project.version`) и `clikit/__init__.py`
+(`__version__`) должны совпадать с тегом (`0.1.0` ↔ `v0.1.0`). Запись в
+`CHANGELOG.md` под этой версией присутствует.
+
+## 1. Привязать origin (один раз)
+
+`<PAT>` — GitLab Personal Access Token со scope `write_repository` (или
+`api`). Токен в URL = «git-over-https» аутентификация для push без интерактива.
+
+```bash
+git remote add origin https://oauth2:<PAT>@gitlab.com/cemon345rus/clikit.git
+# если origin уже есть и нужно сменить:
+# git remote set-url origin https://oauth2:<PAT>@gitlab.com/cemon345rus/clikit.git
+git remote -v   # проверить
+```
+
+> Безопасность: PAT в `remote-url` оседает в `.git/config` открытым текстом.
+> Приемлемо для локального репозитория, но НЕ копировать `.git/config` в
+> передаваемые артефакты. Альтернатива без утечки — git credential helper или
+> `GIT_ASKPASS` (токен не попадает в коммитимый файл).
+
+## 2. Поставить тег релиза
+
+```bash
+git tag -a v0.1.0 -m "clikit v0.1.0 — ядро стандарт-библиотеки CLI"
+git tag   # убедиться, что v0.1.0 появился
+```
+
+Аннотированный тег (`-a`) несёт сообщение и автора — предпочтительнее
+легковесного, потребители ссылаются именно на `@v0.1.0`.
+
+## 3. Запушить ветку и тег
+
+```bash
+git push -u origin main      # код
+git push origin v0.1.0       # тег (теги не уходят с обычным push без --tags)
+# или одной командой: git push origin main --follow-tags
+```
+
+После push сверить три точки: локальный `HEAD` == `origin/main` == тег `v0.1.0`
+указывает на тот же коммит (`git log -1 --oneline` локально и в GitLab UI).
+
+## 4. Потребление в любом CLI-навыке
+
+В `pyproject.toml` навыка-потребителя добавить CLIkit в `dependencies` как
+git-зависимость, закреплённую тегом:
+
+```toml
+[project]
+dependencies = [
+    "clikit @ git+https://gitlab.com/cemon345rus/clikit.git@v0.1.0",
+    # ... доменные зависимости навыка ...
+]
+```
+
+Для прямой git-ссылки нужно разрешить direct references (hatchling):
+
+```toml
+[tool.hatch.metadata]
+allow-direct-references = true
+```
+
+Затем в каталоге навыка:
+
+```bash
+uv sync          # uv авто-подтянет clikit из GitLab по тегу v0.1.0
+```
+
+`uv sync` резолвит git-зависимость, клонирует репозиторий на теге и ставит пакет
+в окружение навыка. Никакого `pip install` вручную, никакого vendoring.
+
+Опциональные экстра (когда появятся, см. `BACKLOG.md`) подключаются через
+extras-маркер: `"clikit[browser] @ git+...@v0.2.0"`.
+
+### Приватный репозиторий
+
+Если репозиторий CLIkit приватный, у потребителя при `uv sync` тоже должен быть
+доступ. Варианты: тот же PAT в URL зависимости (утечёт в lock — нежелательно),
+либо `~/.netrc` / git credential helper / `UV_INDEX`-конфиг с токеном вне
+`pyproject.toml`. Предпочтителен helper — токен не попадает в коммитимый файл.
+
+## 5. Следующие релизы
+
+1. Разработка фичи — в ветке (`git switch -c feat/<name>`), не на `main`.
+2. Влить в `main`, обновить версию (`pyproject.toml` + `__init__.py`) и
+   `CHANGELOG.md` (новая секция `## [X.Y.Z]`).
+3. Повторить шаги 0, 2, 3 для нового тега `vX.Y.Z`.
+4. Потребители обновляются сменой `@vX.Y.Z` в своём `pyproject.toml` + `uv sync`
+   (закреплённый тег = воспроизводимость; обновление осознанное, не «плывёт»).
+
+SemVer: breaking-изменение публичного API (`clikit.__all__`) → мажор; новые
+символы/поля при сохранённом контракте → минор; фиксы — патч.