skrepka 0.9.0__tar.gz

skrepka-0.9.0/.claude-plugin/marketplace.json

@@ -0,0 +1,13 @@
+{
+  "name": "skrepka",
+  "owner": {
+    "name": "Slava Ufimtsev"
+  },
+  "plugins": [
+    {
+      "name": "skrepka",
+      "source": "./",
+      "description": "Careful collaborative editing of Google Docs for AI agents — read and answer comments, apply anchor-safe text edits, upload/download markdown."
+    }
+  ]
+}

skrepka-0.9.0/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "skrepka",
+  "description": "Careful collaborative editing of Google Docs for AI agents — read and answer comments, apply anchor-safe text edits, upload/download markdown, without destroying comment anchors or styles.",
+  "author": {
+    "name": "Slava Ufimtsev",
+    "url": "https://github.com/slvfmts/skrepka"
+  },
+  "homepage": "https://github.com/slvfmts/skrepka",
+  "repository": "https://github.com/slvfmts/skrepka",
+  "license": "MIT",
+  "keywords": ["google-docs", "markdown", "comments", "editing", "agents"]
+}

skrepka-0.9.0/.gitignore

@@ -0,0 +1,35 @@
+# credentials & tokens — never commit
+credentials.json
+client_secret_*.json
+token.json
+*.token.json
+.env
+.env.*
+
+# skrepka runtime artifacts
+*.gdocs-base.json
+*.gdocs-sync-journal.json
+*.merged.md
+
+# python
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+
+# maintainer working context — never published (see pyproject sdist allowlist)
+internal/
+
+# os / editors
+.DS_Store
+.idea/
+.vscode/
+
+# generated diagnostics / media sources
+doctor-report*.json
+*.gif.src/

skrepka-0.9.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+Формат: [Keep a Changelog](https://keepachangelog.com/ru/1.1.0/), версии по [SemVer](https://semver.org/lang/ru/). До 1.0 публичный контракт может меняться.
+
+## [Unreleased]
+
+## [0.9.0] — 2026-07-30
+
+Первый публичный релиз. Предрелизная линия: до 1.0 публичный контракт может меняться.
+
+### Основное
+
+- Комментарии из CLI: `comments` (чтение с пагинацией), `reply`, `comment`, `suggestions`. Резолв (`resolve` / `reply --resolve`) требует подтверждения человека; агент не резолвит сам.
+- Якорно-безопасные правки текста: `patch` через `replaceAllText` с картой якорей из DOCX-экспорта. Правки, полностью накрывающие якорь живого комментария, отклоняются с подсказкой, как переписать; частичное перекрытие разрешено.
+- Загрузка и выгрузка: `upload` / `update` (markdown → документ) и `download` (документ → markdown). Деструктивное полное обновление документа с комментариями блокируется, пока не подтверждено явно, с автоматическим бэкапом.
+- Мастер настройки: `init` (пошаговая авторизация в Google, свой OAuth-клиент, smoke-тест) и `doctor` (диагностика кредов, токена, scope, включённости API).
+- Управление локальными данными: `logout` (убрать токен), `revoke` (отозвать на стороне Google, server-first) и `forget` (best-effort удаление артефактов).
+- `sync` (markdown → документ, three-way merge): экспериментальный, не входит в поддержанный сценарий 0.9.
+- Навыки для агента: единое дерево `skills/` в открытом формате `SKILL.md` для Claude Code и OpenAI Codex. Сценарии: «отработай комментарии», «выгрузи/залей», «опубликуй», «разбери предложения», «что нового». В каждый навык вшито ядро безопасности из [agents/CONTRACT.md](agents/CONTRACT.md); CI проверяет его байт-равенство. Установка: [docs/PLUGIN.md](docs/PLUGIN.md).
+
+### Безопасность
+
+- Запрашивается единственный OAuth-scope `.../auth/drive` (избыточный `documents` убран).
+- Все артефакты пишутся через защищённый I/O (`O_NOFOLLOW` + атомарный `rename`): подменённый по предсказуемому пути симлинк/хардлинк не приводит к записи сквозь него.
+- Токен: `0600` в конфиг-директории `0700`; рефреш с урезанным scope не сохраняется.
+- Резолв комментария (`resolve` / `reply --resolve`) и деструктивное обновление с обнаруженной потерей комментариев/именованных диапазонов (`update --acknowledge-loss`) требуют подтверждения в TTY (неинтерактивный обход: `SKREPKA_ASSUME_HUMAN=1`). Гейт срабатывает при наличии комментариев или именованных диапазонов; документ без тех и других полностью перезаписывается без гейта. Команды управления данными `revoke`/`forget` имеют собственный `--yes`. Это кооперативные границы для агента (см. [PRIVACY.md](PRIVACY.md) и [SECURITY.md](SECURITY.md)), а не криптографические гарантии.
+- Картинки в markdown загружаются только из каталога самого `.md` и его подкаталогов. Абсолютный путь, выход через `../` и симлинк за пределы дерева отклоняются: markdown может быть выгрузкой документа, который писали посторонние, и такая ссылка иначе отправила бы в Drive произвольный локальный файл, на время вставки публично читаемый.
+- SVG не загружается: принимаются только растровые форматы. Рендерер SVG открывает ссылки изнутри файла, а песочницы для него в 0.9 нет.
+- Нет сервера, нет телеметрии. См. [PRIVACY.md](PRIVACY.md) и [SECURITY.md](SECURITY.md).
+
+### Известные ограничения
+
+- Ограничения 0.9 (single-tab, таблицы/сноски только в UI и др.): [docs/LIMITATIONS.md](docs/LIMITATIONS.md).
+- Платформа: Unix. Windows в 0.9 не поддержан.

skrepka-0.9.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Slava Ufimtsev
+
+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.

skrepka-0.9.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: skrepka
+Version: 0.9.0
+Summary: Careful collaborative editing for Google Docs: reply to comments and edit text without ghosting anchors and without flattening styles.
+Project-URL: Homepage, https://github.com/slvfmts/skrepka
+Project-URL: Issues, https://github.com/slvfmts/skrepka/issues
+Author: Slava Ufimtsev
+License: MIT
+License-File: LICENSE
+Keywords: claude,comments,editing,google-docs,markdown
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.11
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: google-api-python-client>=2.100
+Requires-Dist: google-auth-httplib2>=0.1
+Requires-Dist: google-auth-oauthlib>=1.0
+Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: markdownify>=0.11
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: svg
+Requires-Dist: cairosvg>=2.7; extra == 'svg'
+Description-Content-Type: text/markdown
+
+# skrepka 📎
+
+ИИ-соавтор в Google Документах. Агент работает из вашего терминала прямо в документе: читает комментарии, отвечает на них и правит текст на месте.
+
+[In English](https://github.com/slvfmts/skrepka/blob/main/README.en.md) · [Приватность](https://github.com/slvfmts/skrepka/blob/main/PRIVACY.md) · [Безопасность](https://github.com/slvfmts/skrepka/blob/main/SECURITY.md)
+
+## Зачем
+
+Работа над текстом с ИИ обычно идёт в двух окнах: документ и чат с агентом. Скопировать абзац в чат, вставить ответ обратно, руками починить оформление. Пока текст ходит туда-сюда, теряются правки и комментарии.
+
+skrepka убирает это копирование. Вы оставляете по тексту обычные комментарии: про структуру, логику, формулировки. Потом зовёте агента в документ, он читает треды, отвечает и правит текст на месте. Заказчик приходит, комментирует там же, работа продолжается тем же способом. Комментарии при этом не рвутся: якоря остаются на месте, а закрывает треды только человек.
+
+## Для кого
+
+Редакторам, копирайтерам и контент-менеджерам, которые ведут и согласовывают тексты в Google Docs, а к работе подключают ИИ-агента: Claude Code, Codex или другого. Быть разработчиком не нужно, доступ к Google настраивает мастер `skrepka init`.
+
+## Что умеет
+
+Главный сценарий — разобрать комментарии. Вы говорите агенту «отработай комментарии», он читает треды, отвечает по делу и вносит правки в текст.
+
+Кроме этого skrepka выгружает документ в markdown и заливает правки обратно, создаёт документы из markdown и разбирает предложенные правки. Полный список сценариев — в [docs/PLUGIN.md](https://github.com/slvfmts/skrepka/blob/main/docs/PLUGIN.md).
+
+## Как начать
+
+1. Поставьте skrepka: `pipx install skrepka`.
+2. Настройте доступ к Google: `skrepka init`. Первая настройка занимает 15–30 минут, инструкция со снимками экрана — в [docs/QUICKSTART.md](https://github.com/slvfmts/skrepka/blob/main/docs/QUICKSTART.md).
+3. Подключите навыки к агенту: [docs/PLUGIN.md](https://github.com/slvfmts/skrepka/blob/main/docs/PLUGIN.md).
+
+Дальше попросите агента отработать комментарии в тестовом документе.
+
+Вы заводите собственный проект Google Cloud и работаете от своего имени. У skrepka нет сервера и телеметрии: автор skrepka ваших документов и токенов не видит. Подробности в [PRIVACY.md](https://github.com/slvfmts/skrepka/blob/main/PRIVACY.md).
+
+## Документация
+
+| Файл | Что внутри |
+|---|---|
+| [docs/QUICKSTART.md](https://github.com/slvfmts/skrepka/blob/main/docs/QUICKSTART.md) | Настройка доступа к Google по шагам |
+| [docs/PLUGIN.md](https://github.com/slvfmts/skrepka/blob/main/docs/PLUGIN.md) | Навыки для Claude Code и Codex |
+| [docs/LIMITATIONS.md](https://github.com/slvfmts/skrepka/blob/main/docs/LIMITATIONS.md) | Что 0.9 не делает |
+| [PRIVACY.md](https://github.com/slvfmts/skrepka/blob/main/PRIVACY.md) | Какие данные и куда идут |
+| [SECURITY.md](https://github.com/slvfmts/skrepka/blob/main/SECURITY.md) | Модель угроз и как сообщить об уязвимости |
+
+## Лицензия
+
+MIT

skrepka-0.9.0/PRIVACY.md

@@ -0,0 +1,84 @@
+# Приватность skrepka
+
+skrepka — открытая утилита командной строки. Она даёт ИИ-агенту (Claude Code, OpenAI Codex и подобным) доступ к вашим Google Документам: читать, комментировать и править их.
+
+## Кто видит ваши документы
+
+У skrepka нет сервера и нет телеметрии, поэтому автор skrepka ваши данные не видит: документы, токены и текст к нему не попадают ни в каком виде.
+
+Получателей ваших данных трое, и все трое — ваши. Google, где документы и так лежат: с ним skrepka общается от вашего имени. Ваш ИИ-провайдер, тот, на чьих серверах работает агент: Anthropic для Claude, OpenAI для Codex или другой, кого вы выбрали. И, на несколько секунд при вставке картинки, любой, кто знает прямую ссылку на неё в вашем Drive — об этом отдельно ниже.
+
+Токен доступа к Google лежит у вас на диске.
+
+## Кто есть кто
+
+**Автор skrepka** поставляет вам код, и на этом всё. Сервера, телеметрии и доступа к вашим данным у него нет.
+
+**Вы** создаёте собственный проект Google Cloud и собственный OAuth-клиент, то есть подключаетесь к Google от своего имени и своими ключами. Поэтому именно вы отвечаете за то, как используется этот доступ: за право работать с конкретным документом и за настройки приватности вашего ИИ-провайдера.
+
+**ИИ-провайдера** выбираете вы. Агент работает на его серверах, и всё, что агент читает из ваших документов, отправляется этому провайдеру и обрабатывается по его условиям, а не по нашим.
+
+## Какие данные и куда уходят
+
+Поток данных двусторонний.
+
+### Наружу, к агенту и его ИИ-провайдеру
+
+Чтобы агент осмысленно работал с документом, ему уходит больше, чем просто текст: текст документа и комментариев, идентификаторы и ревизии, заголовки, структура, стили и ссылки, авторы и метаданные комментариев, предложенные правки (suggestions), изображения, а также выходные файлы, которые создаёт skrepka. Всё это попадает к вашему ИИ-провайдеру, потому что именно на его серверах живёт агент, который это читает.
+
+### Обратно, изменения в ваших документах
+
+По команде агента skrepka создаёт и изменяет документы, создаёт комментарии и ответы. Это реальные действия в вашем Google Drive, а не черновики; отменять их придётся вручную (частично помогает история версий Google Docs).
+
+Удалять ваши документы skrepka не умеет: такой команды в ней нет, она удаляет только то, что создала сама (временные файлы картинок, тестовый документ в `init`). Но токен, который вы ей выдали, имеет полный доступ к Drive, поэтому граница здесь — не права, а набор команд.
+
+### Изображения и временно публичный доступ
+
+Когда skrepka вставляет изображение, Google Docs API требует, чтобы картинка была доступна по прямой ссылке. Поэтому во время вставки изображение становится временно публичным (`anyone:reader`), а затем публичный доступ снимается. Если процесс упадёт в неудачный момент, картинка может остаться публичной — тогда убрать её нужно вручную в вашем Google Drive.
+
+Сама skrepka картинки со сторонних хостов не скачивает: при выгрузке документа она забирает только изображения с серверов Google, а внешние ссылки оставляет в `.md` как есть. Открывать их будет то, чем вы этот файл просматриваете, — не skrepka.
+
+## Что происходит у ИИ-провайдера
+
+Условия у каждого провайдера свои: сколько времени хранятся запросы, используются ли они для обучения моделей, могут ли их просматривать люди-ревьюеры, каких субподрядчиков он привлекает. skrepka на это не влияет и ничего за провайдера не гарантирует.
+
+Проверьте сами, прежде чем дать агенту доступ к чувствительным документам:
+
+- Claude / Anthropic. Проверьте настройки хранения и обучения в вашем тарифе; условия потребительских и корпоративных (API, Work, Enterprise) планов различаются. Выбирайте режим, где ваши данные не идут в обучение общей модели.
+- Codex / OpenAI. Здесь так же: у API- и потребительских продуктов разные правила обучения и хранения.
+- Любой другой провайдер. Найдите его условия хранения и обучения и убедитесь, что они вас устраивают. Если провайдер предлагает режим ручного просмотра (human review), считайте его отдельным риском для чувствительного контента.
+
+## Где данные лежат на вашем компьютере
+
+Ни одна из локальных копий не уходит автору skrepka.
+
+**OAuth-токен доступа к Google** skrepka пишет с правами `0600` в конфигурационную директорию `~/.config/skrepka/`, которую создаёт с правами `0700`. Права `0600` мешают другим пользователям того же компьютера прочитать файл, но ничего не шифруют. Кто угодно с доступом к диску — украденный незашифрованный ноутбук, резервная копия, другой процесс под вашим же пользователем — сможет прочитать токен. По-настоящему данные «в покое» защищает только полнодисковое шифрование: FileVault на macOS, LUKS на Linux. Включите его, если работаете с чувствительными документами. Прозрачное шифрование самого токена (OS keyring / AEAD) в 0.9 не реализовано, появится в следующих версиях.
+
+**Sidecar-файлы.** Когда вы скачиваете документ для локальной правки, рядом с вашим `.md` skrepka кладёт служебный sidecar с полным текстом документа — это база для слияния. Он лежит в вашей рабочей директории. Если это git-репозиторий, следите, чтобы полный текст не попал в коммит: sidecar-файлы стоит держать в `.gitignore`.
+
+**Скачанные markdown и изображения** тоже лежат в вашей рабочей директории. Все файлы skrepka пишет с правами `0600`, директории с правами `0700`.
+
+## Хранение и удаление данных
+
+Локальными данными управляют три команды.
+
+- `logout`. Убирает из локального хранилища токен доступа и все служебные (smoke/cleanup) токены, чтобы агент больше не мог обращаться к Google от вашего имени. OAuth-клиент (`credentials.json`) сохраняется, чтобы быстро подключиться заново. Доступ на стороне Google при этом не отзывается.
+- `revoke`. Обращается к серверу Google и отзывает refresh-токен. Это сильнее `logout`. Предупреждение: отзыв может снять все разрешения для всего вашего OAuth-проекта и обесценить токены других клиентов этого же проекта. Если Google не подтвердил отзыв однозначно (таймаут, сетевая ошибка, неоднозначный ответ), skrepka оставит токен и сообщит, что результат неясен, вместо того чтобы делать вид, будто всё удалено.
+- `forget`. Удаляет локальные артефакты: токен, `credentials.json`, служебные журналы и токены, файлы восстановления. Что удалить не удалось, команда перечислит отдельно. Файл блокировки (`.lock`) и сама директория остаются. По отдельному пути (`--sidecars PATH`) удаляет sidecar рядом с вашим документом, сам ваш `.md` не трогает. Есть предпросмотр: `--dry-run`.
+
+**Чего локальное удаление не касается.** Оно стирает только локальные копии. За его пределами остаются копии, уже сохранённые у Google (документы, комментарии, история версий, оставшиеся публичными картинки), и копии у ИИ-провайдера — они хранятся по его политике. Так же за его пределами остаются данные в git-истории, резервных копиях и снапшотах.
+
+## Про обучение моделей и данные Google
+
+skrepka сама не собирает данные, не строит и не обучает никаких моделей и не передаёт данные автору (нет сервера, нет телеметрии). Данные Google уходят только тому ИИ-провайдеру, которого выбрали вы, и обрабатываются по его условиям. Поскольку вы работаете через собственный OAuth-проект, к нему применяется Google API Services User Data Policy. Режим без обучения на ваших данных выбираете у провайдера вы сами, skrepka этого не гарантирует.
+
+## Ваша ответственность как владельца доступа
+
+Доступ к Google идёт через ваш OAuth-проект и ваши ключи, поэтому:
+
+- у вас должны быть полномочия работать с документом. Если вы правите или комментируете чужой документ (заказчика, Shared Drive), убедитесь, что владелец дал вам на это право. skrepka ваши полномочия технически не проверяет, она действует от вашего имени;
+- если вы публикуете свой OAuth-клиент как публичное приложение, на вас ложатся требования Google: политика приватности, возможная верификация и аудит CASA. Для персонального использования это обычно не требуется.
+
+## Статус 0.9
+
+Вы работаете через собственный Google-проект и от своего имени; это не приложение, в которое входят под общей учётной записью. Верификацию Google, если она вообще нужна, проходит ваш проект, а не автор skrepka. Технические детали защит на уровне CLI (гейты на резолв комментариев и на деструктивную перезапись, безопасный ввод-вывод) описаны в [SECURITY.md](SECURITY.md). На этом этапе skrepka показывает, какие данные куда идут, и даёт ими управлять, но не гарантирует соответствие требованиям Google.

skrepka-0.9.0/README.en.md

@@ -0,0 +1,45 @@
+# skrepka 📎
+
+An AI co-author in Google Docs. The agent works from your terminal inside the document itself: it reads the comments, replies to them, and edits the text in place.
+
+*In Russian: [README.md](README.md).*
+
+## Why
+
+Working on text with an AI usually means two windows: the document and a chat with the agent. Copy a paragraph into the chat, paste the answer back, fix the formatting by hand. While the text travels back and forth, edits and comments get lost.
+
+skrepka removes the copying. You leave ordinary comments in the text about structure, logic, and wording. Then you point the agent at the document; it reads the threads, replies, and edits the text in place. Your client shows up, comments in the same document, and the work continues the same way. The comments survive: anchors stay put, and only a human closes a thread.
+
+## Who it is for
+
+Editors, copywriters, and content managers who run and sign off documents in Google Docs and bring an AI agent into the work: Claude Code, Codex, or another one. You do not need to be a developer; the `skrepka init` wizard sets up Google access for you.
+
+## What it does
+
+The main scenario is working through comments. You tell the agent to handle the comments; it reads the threads, replies to the point, and edits the text.
+
+skrepka also exports a document to markdown and pushes edits back, creates documents from markdown, and reviews suggested changes. Full list of scenarios in [docs/PLUGIN.md](docs/PLUGIN.md).
+
+## Getting started
+
+1. Install skrepka: `pipx install skrepka`.
+2. Set up Google access: `skrepka init`. First-time setup takes 15 to 30 minutes; the walkthrough with screenshots is in [docs/QUICKSTART.md](docs/QUICKSTART.md).
+3. Connect the skills to your agent: [docs/PLUGIN.md](docs/PLUGIN.md).
+
+Then ask the agent to work through the comments in a test document.
+
+You create your own Google Cloud project and act under your own account. skrepka has no server and no telemetry: its author never sees your documents or your tokens. Details in [PRIVACY.md](PRIVACY.md).
+
+## Docs
+
+| File | What's inside |
+|---|---|
+| [docs/QUICKSTART.md](docs/QUICKSTART.md) | Step-by-step Google authorization |
+| [docs/PLUGIN.md](docs/PLUGIN.md) | Connecting the skills to your agent |
+| [docs/LIMITATIONS.md](docs/LIMITATIONS.md) | What 0.9 deliberately does not do |
+| [PRIVACY.md](PRIVACY.md) | What data goes where |
+| [SECURITY.md](SECURITY.md) | Threat model and how to report a vulnerability |
+
+## License
+
+MIT

skrepka-0.9.0/README.md

@@ -0,0 +1,45 @@
+# skrepka 📎
+
+ИИ-соавтор в Google Документах. Агент работает из вашего терминала прямо в документе: читает комментарии, отвечает на них и правит текст на месте.
+
+[In English](https://github.com/slvfmts/skrepka/blob/main/README.en.md) · [Приватность](https://github.com/slvfmts/skrepka/blob/main/PRIVACY.md) · [Безопасность](https://github.com/slvfmts/skrepka/blob/main/SECURITY.md)
+
+## Зачем
+
+Работа над текстом с ИИ обычно идёт в двух окнах: документ и чат с агентом. Скопировать абзац в чат, вставить ответ обратно, руками починить оформление. Пока текст ходит туда-сюда, теряются правки и комментарии.
+
+skrepka убирает это копирование. Вы оставляете по тексту обычные комментарии: про структуру, логику, формулировки. Потом зовёте агента в документ, он читает треды, отвечает и правит текст на месте. Заказчик приходит, комментирует там же, работа продолжается тем же способом. Комментарии при этом не рвутся: якоря остаются на месте, а закрывает треды только человек.
+
+## Для кого
+
+Редакторам, копирайтерам и контент-менеджерам, которые ведут и согласовывают тексты в Google Docs, а к работе подключают ИИ-агента: Claude Code, Codex или другого. Быть разработчиком не нужно, доступ к Google настраивает мастер `skrepka init`.
+
+## Что умеет
+
+Главный сценарий — разобрать комментарии. Вы говорите агенту «отработай комментарии», он читает треды, отвечает по делу и вносит правки в текст.
+
+Кроме этого skrepka выгружает документ в markdown и заливает правки обратно, создаёт документы из markdown и разбирает предложенные правки. Полный список сценариев — в [docs/PLUGIN.md](https://github.com/slvfmts/skrepka/blob/main/docs/PLUGIN.md).
+
+## Как начать
+
+1. Поставьте skrepka: `pipx install skrepka`.
+2. Настройте доступ к Google: `skrepka init`. Первая настройка занимает 15–30 минут, инструкция со снимками экрана — в [docs/QUICKSTART.md](https://github.com/slvfmts/skrepka/blob/main/docs/QUICKSTART.md).
+3. Подключите навыки к агенту: [docs/PLUGIN.md](https://github.com/slvfmts/skrepka/blob/main/docs/PLUGIN.md).
+
+Дальше попросите агента отработать комментарии в тестовом документе.
+
+Вы заводите собственный проект Google Cloud и работаете от своего имени. У skrepka нет сервера и телеметрии: автор skrepka ваших документов и токенов не видит. Подробности в [PRIVACY.md](https://github.com/slvfmts/skrepka/blob/main/PRIVACY.md).
+
+## Документация
+
+| Файл | Что внутри |
+|---|---|
+| [docs/QUICKSTART.md](https://github.com/slvfmts/skrepka/blob/main/docs/QUICKSTART.md) | Настройка доступа к Google по шагам |
+| [docs/PLUGIN.md](https://github.com/slvfmts/skrepka/blob/main/docs/PLUGIN.md) | Навыки для Claude Code и Codex |
+| [docs/LIMITATIONS.md](https://github.com/slvfmts/skrepka/blob/main/docs/LIMITATIONS.md) | Что 0.9 не делает |
+| [PRIVACY.md](https://github.com/slvfmts/skrepka/blob/main/PRIVACY.md) | Какие данные и куда идут |
+| [SECURITY.md](https://github.com/slvfmts/skrepka/blob/main/SECURITY.md) | Модель угроз и как сообщить об уязвимости |
+
+## Лицензия
+
+MIT

skrepka-0.9.0/SECURITY.md

@@ -0,0 +1,72 @@
+# Безопасность skrepka
+
+Здесь модель угроз, встроенные защиты и порядок сообщения об уязвимости. Про то, какие данные и куда уходят, есть отдельный документ [PRIVACY.md](PRIVACY.md).
+
+skrepka 0.9 — предрелиз. Защиты, описанные ниже, покрыты тестами, но это ещё не проверенное Google приложение.
+
+## Как сообщить об уязвимости
+
+Публичный issue для уязвимости не открывайте. Есть два приватных канала:
+
+- GitHub: вкладка Security → Report a vulnerability (private vulnerability reporting) в репозитории `slvfmts/skrepka`;
+- письмо на hello@editors.one с темой, начинающейся на `[skrepka security]`.
+
+Что приложить: версию skrepka, ОС и версию Python, шаги воспроизведения. Для проблем с файловым вводом-выводом — точную раскладку путей и прав.
+
+Проект некоммерческий, гарантированных сроков ответа нет. Исправление выходит в ближайшем патч-релизе, кредит в релизных заметках указываем по вашему желанию.
+
+## Поддерживаемые версии
+
+skrepka в стадии 0.9 (предрелиз). Исправления безопасности выходят только для последнего релиза линии 0.9.x. Более ранних поддерживаемых веток нет.
+
+## Модель угроз
+
+**От чего защищаем.** skrepka пишет артефакты — скачанный документ, изображения, sidecar, файл `--output` — в ту рабочую директорию, где вы запускаете команду. Цепочку владельцев этой директории skrepka не контролирует. Главная угроза: симлинк или хардлинк, подложенный по предсказуемому пути. Наивный `open(path, "w")` пошёл бы по такой ссылке и переписал содержимым документа произвольный файл, доступный вам на запись, например `~/.ssh/authorized_keys`. Сценарий реален в общих и world-writable каталогах: `/tmp`, расшаренные рабочие директории.
+
+**Где проведена граница.** Защита покрывает имя целевого файла и его непосредственную родительскую директорию, то есть предсказуемые, угадываемые имена. Здесь skrepka работает через `O_NOFOLLOW` и эксклюзивное создание: симлинк на этой позиции приводит к отказу (fail closed).
+
+Директории выше непосредственного родителя относятся к вашей существующей среде, и симлинки в них разыменовываются намеренно. Так работает файловая система, и на macOS иначе нельзя: `/var`, `/tmp`, `/etc` сами ведут в `/private` через симлинки. К тому же тот, кто может подложить симлинк в дальний предок, уже имеет доступ на запись в ваше дерево.
+
+**Что вне модели угроз.**
+
+- Атакующий под вашим же пользователем (тот же UID). Он и так может прочитать токен и ваши файлы. Права `0600`/`0700` закрывают файлы от других пользователей машины, но не шифруют их; подробнее в [PRIVACY.md](PRIVACY.md).
+- Windows. В 0.9 не поддержан; защиты файлового I/O работают только на Unix (`openat`, `O_NOFOLLOW`, dir-fd).
+- Гранулярный контроль каждого действия агента. Вне скоупа 0.9, см. ниже про человеческий гейт и prompt-injection.
+
+## Встроенные защиты
+
+### Аутентификация и доступ
+
+skrepka запрашивает единственный OAuth-scope: `https://www.googleapis.com/auth/drive`. Более узкий `drive.file` неприменим: он ломает ключевой сценарий с чужим документом, к которому обращаются по его ID или через Shared Drive. Дополнительные scope, включая `documents`, не запрашиваются — `drive` уже покрывает нужные вызовы Docs API.
+
+Токен хранится с правами `0600` в конфиг-директории `~/.config/skrepka/` (`0700`). Рефреш с сокращённым набором scope на диск не сохраняется, иначе урезанный грант молча стал бы рабочим при следующем запуске.
+
+### Файловый I/O
+
+Все артефакты пишутся через модуль `safeio`. Непосредственный родитель открывается `O_NOFOLLOW` и создаётся эксклюзивным `mkdir` с правами `0700`. Запись идёт в непредсказуемый временный файл (`O_EXCL|O_NOFOLLOW`), затем атомарный `rename` поверх цели. `rename` заменяет имя: он не пишет сквозь симлинк и не усекает хардлинкнутый inode. Существующая нерегулярная цель отвергается явно.
+
+### Человеческий гейт
+
+У гейта два уровня, и гарантии у них разные.
+
+**Механический барьер, вшитый в код.** Резолв комментария (`resolve`, `reply --resolve`) и деструктивное полное обновление документа (`update --acknowledge-loss`) требуют подтверждения: интерактивный запрос в TTY, по умолчанию «нет». Единственный неинтерактивный обход — переменная окружения `SKREPKA_ASSUME_HUMAN=1`, которую выставляет сам человек. Гейт на `update` срабатывает, когда в документе есть комментарии или именованные диапазоны; документ без тех и других перезаписывается без вопроса.
+
+Гарантии «ответил именно человек» механический барьер не даёт: агент, выделивший псевдотерминал, технически способен ответить на запрос сам. Идентичность человека держится на договорённости ([`agents/CONTRACT.md`](agents/CONTRACT.md)), а не на криптографии. По контракту агент комментарии не резолвит.
+
+**Уровень договорённости, без машинного барьера.** `revoke` и `forget` в неинтерактивном запуске без `--yes` отказывают, но сам флаг `--yes` агент технически может передать. `logout` подтверждения не спрашивает вовсе, он лишь убирает локальный токен. Запрет запускать эти команды за человека записан в правилах для агента ([`agents/CONTRACT.md`](agents/CONTRACT.md)). Это команды для человека.
+
+### Изображения
+
+Вставка картинки требует временно публичной прямой ссылки: на время вставки файл становится `anyone:reader`, затем доступ снимается. Детали, риск при неудачном падении и рекомендации описаны в [PRIVACY.md](PRIVACY.md).
+
+### Prompt-injection
+
+skrepka считает текст документов и комментариев данными, а не инструкциями. Навыки для агента (см. [`agents/CONTRACT.md`](agents/CONTRACT.md)) обязаны не выполнять просьбы, встреченные внутри комментариев или текста, без подтверждения человека.
+
+### Без телеметрии
+
+У skrepka нет сервера, нет сбора данных и нет исходящих соединений, кроме API самого Google. Картинки она забирает только с Google-хостов, сторонние URL из документа не запрашивает вовсе — это заодно закрывает SSRF. Автор skrepka ваших данных не получает.
+
+## Гигиена репозитория
+
+Секреты (`credentials.json`, `client_secret_*.json`, `token.json`, `*.token.json`, `.env`) перечислены в `.gitignore` и не должны попадать в коммиты. gitleaks прогоняется по всей истории в CI на каждый push и в release-workflow перед публикацией. Артефакты рантайма (`*.gdocs-base.json`, журналы синка) тоже в `.gitignore`: sidecar содержит полный текст документа.