backlog-digest 1.0.0__tar.gz

backlog_digest-1.0.0/.gitignore

@@ -0,0 +1,17 @@
+# Python
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+
+# секрети та локальні дані / secrets and local data
+.env
+config.yaml
+client_secret*.json
+token.json
+*.session
+cookies*.txt
+data/

backlog_digest-1.0.0/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes are listed here. The project follows [Semantic Versioning](https://semver.org/).
+
+## 1.0.0 — first public release
+
+### Sources
+- **YouTube** playlists, channels and single videos through yt-dlp — no Google Cloud, no YouTube keys.
+  Two independent steps: collect subtitles (slow, gentle pauses, daily limit) and write summaries (fast).
+  Stops asking YouTube when it limits your address and keeps summarizing what is already collected.
+- **Folders** of books and documents: PDF, EPUB, FB2, DOCX, ODT, RTF, HTML, TXT, MD; DJVU with DjVuLibre;
+  MOBI, AZW3, DOC with Calibre. Long books are read in parts and continue after a stop.
+- **Web articles**: links, browser bookmarks (HTML export, with folder choice), Pocket, Instapaper, CSV.
+  Main text only.
+- **Raindrop.io** bookmarks (read-only), collections become lists.
+
+### Summaries
+- A note per item: what it is about, key ideas and facts, what is new, grounding and questionable claims,
+  filler with timestamps, audience, verdict and a strict 1–5 score; pseudoscience goes to "Skip".
+- Any summary language; interface in English, Ukrainian, French and Spanish.
+- A queue of models with spares (Gemini, OpenRouter, DeepSeek, your own or local), daily quotas remembered.
+- Output to an Obsidian vault or a plain Markdown folder.
+
+### Library
+- Sorting by topic: your own topics, "important / the rest" baskets or a topic tree proposed by the model,
+  with a preview before anything moves.
+- A report and an index note per list: the best items, everything by topic, groups of repeats, off-topic,
+  unscientific, failed pages.
+- Export to Raindrop.io: nested collections by list and topic, only new and changed items are sent.
+
+### Running
+- First-run wizard: from zero to the first summary in a few minutes.
+- Schedule with catch-up after the computer was off; autostart through Task Scheduler (Windows),
+  launchd (macOS), a systemd timer or cron (Linux), without administrator rights.
+- A data panel above the menu, a desktop shortcut, `bdig doctor` health check.
+- Install with `uv tool install backlog-digest`.

backlog_digest-1.0.0/LICENSE

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

backlog_digest-1.0.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.5
+Name: backlog-digest
+Version: 1.0.0
+Summary: Turn your backlog of saved videos, articles, books and posts into a readable library.
+Project-URL: Homepage, https://github.com/Makss1974/backlog-digest
+Project-URL: Documentation, https://github.com/Makss1974/backlog-digest#readme
+Project-URL: FAQ, https://github.com/Makss1974/backlog-digest/blob/main/docs/FAQ.md
+Project-URL: Changelog, https://github.com/Makss1974/backlog-digest/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Makss1974/backlog-digest/issues
+Author: Makss1974
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bookmarks,gemini,llm,obsidian,raindrop,reading-list,summary,youtube
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Natural Language :: English
+Classifier: Natural Language :: French
+Classifier: Natural Language :: Spanish
+Classifier: Natural Language :: Ukrainian
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Text Processing :: General
+Requires-Python: >=3.11
+Requires-Dist: pypdf>=5
+Requires-Dist: trafilatura<3,>=2
+Requires-Dist: youtube-transcript-api<2,>=1.2
+Requires-Dist: yt-dlp>=2025.1.1
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# backlog-digest
+
+**Work through your "saved for later" pile.** Thousands of saved videos, articles and books →
+a library you can read in an evening.
+
+[Українською](https://github.com/Makss1974/backlog-digest/blob/main/README.uk.md) · [FAQ](https://github.com/Makss1974/backlog-digest/blob/main/docs/FAQ.md) · [Example summary](https://github.com/Makss1974/backlog-digest/blob/main/docs/examples/video-summary.en.md) ·
+License: [MIT](https://github.com/Makss1974/backlog-digest/blob/main/LICENSE)
+
+For every item backlog-digest writes a summary with a **critical score** and an honest **"worth it or not"**
+verdict, flags pseudoscience, sorts everything by topic, finds repeats, and puts the result into **your own**
+Obsidian vault, a plain Markdown folder or Raindrop.io. It runs on your computer with free model keys, works
+through thousands of items a little every day, and never loses progress.
+
+```text
+────────────────────────────────────────────────────────────
+  backlog-digest — 16 of 84 done, 66 in queue
+  waiting for subtitles: 44 (0 of 30 collected today) · ready to summarize: 22 · no text: 2
+  Sources: 2 (YouTube 1, Raindrop 1) · summaries → D:\Obsidian\Library
+  Models: 6 of 7 available · today's limit used up: gemini/gemini-3-flash-preview
+────────────────────────────────────────────────────────────
+   1. Statistics
+   2. Sources: YouTube, folders, articles, Raindrop
+   3. Make summaries
+   4. Sort by topic + report
+   5. Export to Raindrop.io
+   6. Schedule
+   7. Health check (doctor)
+   8. Settings
+   q. Quit
+```
+
+## What you get
+
+A note per item ([full example](https://github.com/Makss1974/backlog-digest/blob/main/docs/examples/video-summary.en.md)):
+
+> **Measles Explained — Vaccinate or Not?** · Kurzgesagt
+>
+> **Verdict: Watch** · Score: 5/5 ★★★★★
+>
+> **About:** how the measles virus bypasses the immune system, and why vaccination matters for herd immunity.
+> **Key ideas and facts:** 10 points with numbers · **What is new** · **Grounding:** evidence level, what the
+> author relies on, questionable claims · **How much filler:** ~10%, with timestamps · **Who it is for** ·
+> **Why this verdict**
+
+Verdicts: *Watch / Read*, *Watch part* (which fragments), *Summary is enough*, *Skip*. The score scale is
+strict on purpose — an average item gets 3, and unscientific content goes to *Skip*.
+
+Then, per list:
+
+- **Sorting by topic** — your own topics, "important / the rest" baskets, or a topic tree the model proposes;
+  notes move into topic folders after you see a preview.
+- **Index note** — the best items, everything by topic with scores, **groups of repeats** (watch only the
+  best one), off-topic and unscientific items, pages that failed.
+- **Raindrop.io export** — nested collections by list and topic, with the summary in the bookmark note.
+
+## Sources
+
+| Source | How |
+|---|---|
+| **YouTube** — playlists, channels, single videos | Subtitles via yt-dlp — no Google Cloud, no YouTube keys |
+| **Folders** of books and documents (also Google Drive / OneDrive / Dropbox folders) | PDF, EPUB, FB2, DOCX, ODT, RTF, HTML, TXT, MD; DJVU with DjVuLibre; MOBI, AZW3, DOC with Calibre |
+| **Web articles** — links, browser bookmarks (HTML export), Pocket, Instapaper, CSV | Main text only (no menus, ads, comments) |
+| **Raindrop.io** bookmarks | Collections become lists; read-only |
+
+Long books are read in parts and continue after a stop. The same video or book in several lists is summarized
+once. YouTube links inside bookmarks become videos, PDF links become books.
+
+## Install
+
+You only need [uv](https://docs.astral.sh/uv/) — a small tool that installs the right Python and
+backlog-digest apart from the rest of your system. No administrator rights.
+
+**1. Install uv** (once). Windows, in PowerShell:
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+macOS and Linux, in a terminal:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+**2. Install backlog-digest**, then close and reopen the terminal:
+
+```bash
+uv tool install backlog-digest
+uv tool update-shell
+```
+
+**3. Run it:**
+
+```bash
+bdig
+```
+
+On the first run a wizard sets everything up in a few minutes — language, notes folder, a model key, the first
+source, how many per day, a daily schedule — and makes your first summary right away.
+`bdig shortcut` puts a desktop shortcut that opens the program in its own window; `bdig doctor` checks that
+everything is in place.
+
+**Model key.** The easiest is a free Google Gemini key: open <https://aistudio.google.com/apikey>, sign in,
+"Create API key", paste it into the wizard. OpenRouter and DeepSeek keys work too and serve as spares when one
+model's daily limit runs out.
+
+Upgrade: `uv tool upgrade backlog-digest`. Uninstall: `bdig autostart off`, then `uv tool uninstall backlog-digest`
+(your notes stay where they are).
+
+## Everyday use
+
+Everything is in the menu (`bdig`); the same works as commands, which is handy for scripts:
+
+```bash
+bdig add "https://www.youtube.com/playlist?list=..." --name Science   # a YouTube source
+bdig add "D:\Books"                                                   # a folder of books
+bdig add bookmarks.html --only "Reading/Science"                      # browser bookmarks, one folder
+bdig add raindrop "Read later"                                        # Raindrop collections
+bdig sync                     # find new items in all sources
+bdig process --limit 20       # collect texts and write summaries
+bdig export                   # send summaries to Raindrop
+bdig run-jobs --force         # run the scheduled jobs now
+```
+
+**Schedule.** Menu → 6: what to do (update lists → summaries → report → Raindrop), how many, daily or weekly,
+"not before HH:MM". Autostart uses the system scheduler without administrator rights — Task Scheduler on
+Windows, launchd on macOS, a systemd timer or cron on Linux. If the computer was off, the job catches up the
+next time. A log goes to a file and to a "_Schedule log" note.
+
+**Gentle with limits.** Free models and YouTube have daily limits, so the program works in portions:
+1–3 minute pauses between subtitle requests, at most 30 subtitle requests a day (configurable), a queue of spare
+models, and if YouTube limits your address it stops asking and keeps summarizing what is already collected.
+Ctrl+C stops at any moment; the next run continues where it stopped.
+
+**Languages.** The interface is in English, Ukrainian, French and Spanish. Summaries can be in any language,
+regardless of the language of the video or book.
+
+## Your data stays yours
+
+- Everything runs on your computer. Notes are plain Markdown files in your folder.
+- Sources are read-only: nothing is changed in YouTube, your bookmarks or Raindrop (the export goes into its own
+  collection).
+- Keys live in environment variables or in a `.env` file in the settings folder; the program never shows them.
+- No telemetry.
+
+| What | Windows | macOS | Linux |
+|---|---|---|---|
+| Settings `config.toml` and keys `.env` | `%APPDATA%\backlog-digest` | `~/Library/Application Support/backlog-digest` | `~/.config/backlog-digest` |
+| Database, cache, logs | `%LOCALAPPDATA%\backlog-digest` | same | `~/.local/share/backlog-digest` |
+
+`BACKLOG_DIGEST_HOME=<folder>` (or `bdig --home <folder>`) keeps everything in one folder.
+
+## More
+
+- [FAQ](https://github.com/Makss1974/backlog-digest/blob/main/docs/FAQ.md): limits, blocked YouTube, scanned books, long paths on Windows and other pitfalls.
+- [Development](https://github.com/Makss1974/backlog-digest/blob/main/docs/development.md): running from source, tests, project layout.
+- [Specification](https://github.com/Makss1974/backlog-digest/blob/main/docs/ТЗ.md) (Ukrainian).
+
+Grew out of the author's personal tool `yt-digest`, used daily for video summaries.

backlog_digest-1.0.0/README.md

@@ -0,0 +1,159 @@
+# backlog-digest
+
+**Work through your "saved for later" pile.** Thousands of saved videos, articles and books →
+a library you can read in an evening.
+
+[Українською](https://github.com/Makss1974/backlog-digest/blob/main/README.uk.md) · [FAQ](https://github.com/Makss1974/backlog-digest/blob/main/docs/FAQ.md) · [Example summary](https://github.com/Makss1974/backlog-digest/blob/main/docs/examples/video-summary.en.md) ·
+License: [MIT](https://github.com/Makss1974/backlog-digest/blob/main/LICENSE)
+
+For every item backlog-digest writes a summary with a **critical score** and an honest **"worth it or not"**
+verdict, flags pseudoscience, sorts everything by topic, finds repeats, and puts the result into **your own**
+Obsidian vault, a plain Markdown folder or Raindrop.io. It runs on your computer with free model keys, works
+through thousands of items a little every day, and never loses progress.
+
+```text
+────────────────────────────────────────────────────────────
+  backlog-digest — 16 of 84 done, 66 in queue
+  waiting for subtitles: 44 (0 of 30 collected today) · ready to summarize: 22 · no text: 2
+  Sources: 2 (YouTube 1, Raindrop 1) · summaries → D:\Obsidian\Library
+  Models: 6 of 7 available · today's limit used up: gemini/gemini-3-flash-preview
+────────────────────────────────────────────────────────────
+   1. Statistics
+   2. Sources: YouTube, folders, articles, Raindrop
+   3. Make summaries
+   4. Sort by topic + report
+   5. Export to Raindrop.io
+   6. Schedule
+   7. Health check (doctor)
+   8. Settings
+   q. Quit
+```
+
+## What you get
+
+A note per item ([full example](https://github.com/Makss1974/backlog-digest/blob/main/docs/examples/video-summary.en.md)):
+
+> **Measles Explained — Vaccinate or Not?** · Kurzgesagt
+>
+> **Verdict: Watch** · Score: 5/5 ★★★★★
+>
+> **About:** how the measles virus bypasses the immune system, and why vaccination matters for herd immunity.
+> **Key ideas and facts:** 10 points with numbers · **What is new** · **Grounding:** evidence level, what the
+> author relies on, questionable claims · **How much filler:** ~10%, with timestamps · **Who it is for** ·
+> **Why this verdict**
+
+Verdicts: *Watch / Read*, *Watch part* (which fragments), *Summary is enough*, *Skip*. The score scale is
+strict on purpose — an average item gets 3, and unscientific content goes to *Skip*.
+
+Then, per list:
+
+- **Sorting by topic** — your own topics, "important / the rest" baskets, or a topic tree the model proposes;
+  notes move into topic folders after you see a preview.
+- **Index note** — the best items, everything by topic with scores, **groups of repeats** (watch only the
+  best one), off-topic and unscientific items, pages that failed.
+- **Raindrop.io export** — nested collections by list and topic, with the summary in the bookmark note.
+
+## Sources
+
+| Source | How |
+|---|---|
+| **YouTube** — playlists, channels, single videos | Subtitles via yt-dlp — no Google Cloud, no YouTube keys |
+| **Folders** of books and documents (also Google Drive / OneDrive / Dropbox folders) | PDF, EPUB, FB2, DOCX, ODT, RTF, HTML, TXT, MD; DJVU with DjVuLibre; MOBI, AZW3, DOC with Calibre |
+| **Web articles** — links, browser bookmarks (HTML export), Pocket, Instapaper, CSV | Main text only (no menus, ads, comments) |
+| **Raindrop.io** bookmarks | Collections become lists; read-only |
+
+Long books are read in parts and continue after a stop. The same video or book in several lists is summarized
+once. YouTube links inside bookmarks become videos, PDF links become books.
+
+## Install
+
+You only need [uv](https://docs.astral.sh/uv/) — a small tool that installs the right Python and
+backlog-digest apart from the rest of your system. No administrator rights.
+
+**1. Install uv** (once). Windows, in PowerShell:
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+macOS and Linux, in a terminal:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+**2. Install backlog-digest**, then close and reopen the terminal:
+
+```bash
+uv tool install backlog-digest
+uv tool update-shell
+```
+
+**3. Run it:**
+
+```bash
+bdig
+```
+
+On the first run a wizard sets everything up in a few minutes — language, notes folder, a model key, the first
+source, how many per day, a daily schedule — and makes your first summary right away.
+`bdig shortcut` puts a desktop shortcut that opens the program in its own window; `bdig doctor` checks that
+everything is in place.
+
+**Model key.** The easiest is a free Google Gemini key: open <https://aistudio.google.com/apikey>, sign in,
+"Create API key", paste it into the wizard. OpenRouter and DeepSeek keys work too and serve as spares when one
+model's daily limit runs out.
+
+Upgrade: `uv tool upgrade backlog-digest`. Uninstall: `bdig autostart off`, then `uv tool uninstall backlog-digest`
+(your notes stay where they are).
+
+## Everyday use
+
+Everything is in the menu (`bdig`); the same works as commands, which is handy for scripts:
+
+```bash
+bdig add "https://www.youtube.com/playlist?list=..." --name Science   # a YouTube source
+bdig add "D:\Books"                                                   # a folder of books
+bdig add bookmarks.html --only "Reading/Science"                      # browser bookmarks, one folder
+bdig add raindrop "Read later"                                        # Raindrop collections
+bdig sync                     # find new items in all sources
+bdig process --limit 20       # collect texts and write summaries
+bdig export                   # send summaries to Raindrop
+bdig run-jobs --force         # run the scheduled jobs now
+```
+
+**Schedule.** Menu → 6: what to do (update lists → summaries → report → Raindrop), how many, daily or weekly,
+"not before HH:MM". Autostart uses the system scheduler without administrator rights — Task Scheduler on
+Windows, launchd on macOS, a systemd timer or cron on Linux. If the computer was off, the job catches up the
+next time. A log goes to a file and to a "_Schedule log" note.
+
+**Gentle with limits.** Free models and YouTube have daily limits, so the program works in portions:
+1–3 minute pauses between subtitle requests, at most 30 subtitle requests a day (configurable), a queue of spare
+models, and if YouTube limits your address it stops asking and keeps summarizing what is already collected.
+Ctrl+C stops at any moment; the next run continues where it stopped.
+
+**Languages.** The interface is in English, Ukrainian, French and Spanish. Summaries can be in any language,
+regardless of the language of the video or book.
+
+## Your data stays yours
+
+- Everything runs on your computer. Notes are plain Markdown files in your folder.
+- Sources are read-only: nothing is changed in YouTube, your bookmarks or Raindrop (the export goes into its own
+  collection).
+- Keys live in environment variables or in a `.env` file in the settings folder; the program never shows them.
+- No telemetry.
+
+| What | Windows | macOS | Linux |
+|---|---|---|---|
+| Settings `config.toml` and keys `.env` | `%APPDATA%\backlog-digest` | `~/Library/Application Support/backlog-digest` | `~/.config/backlog-digest` |
+| Database, cache, logs | `%LOCALAPPDATA%\backlog-digest` | same | `~/.local/share/backlog-digest` |
+
+`BACKLOG_DIGEST_HOME=<folder>` (or `bdig --home <folder>`) keeps everything in one folder.
+
+## More
+
+- [FAQ](https://github.com/Makss1974/backlog-digest/blob/main/docs/FAQ.md): limits, blocked YouTube, scanned books, long paths on Windows and other pitfalls.
+- [Development](https://github.com/Makss1974/backlog-digest/blob/main/docs/development.md): running from source, tests, project layout.
+- [Specification](https://github.com/Makss1974/backlog-digest/blob/main/docs/ТЗ.md) (Ukrainian).
+
+Grew out of the author's personal tool `yt-digest`, used daily for video summaries.

backlog_digest-1.0.0/README.uk.md

@@ -0,0 +1,217 @@
+# backlog-digest
+
+**Розбери свої завали.** Тисячі збережених відео, статей і книг → бібліотека, яку можна прочитати за вечір.
+
+[English](README.md) · [Питання й відповіді](docs/FAQ.uk.md) · [Приклад конспекту](docs/examples/video-summary.uk.md) ·
+Ліцензія: [MIT](LICENSE)
+
+Для кожного елемента backlog-digest пише конспект із **критичною оцінкою** й чесним вердиктом **«варто чи ні»**,
+позначає псевдонауку, розкладає все за темами, знаходить повтори й складає результат у **ваше** сховище Obsidian,
+звичайну теку Markdown або Raindrop.io. Працює на вашому комп'ютері з безкоштовними ключами моделей, розбирає
+тисячі елементів потроху щодня й ніколи не губить прогрес.
+
+```text
+────────────────────────────────────────────────────────────
+  backlog-digest — готово 16 з 84, у черзі 66
+  чекають субтитрів: 44 (сьогодні зібрано 0 з 30) · готові до конспекту: 22 · без тексту: 2
+  Джерела: 2 (YouTube 1, Raindrop 1) · конспекти → D:\Obsidian\Бібліотека
+  Моделі: доступно 6 з 7 · ліміт на сьогодні вичерпано: gemini/gemini-3-flash-preview
+────────────────────────────────────────────────────────────
+   1. Статистика
+   2. Джерела: YouTube, папки, статті, Raindrop
+   3. Зробити конспекти
+   4. Сортування за темами + звіт
+   5. Експорт у Raindrop.io
+   6. Розклад
+   7. Перевірка (doctor)
+   8. Налаштування
+   q. Вихід
+```
+
+## Що виходить
+
+Нотатка на кожен елемент ([повний приклад](docs/examples/video-summary.uk.md)):
+
+> **Measles Explained — Vaccinate or Not?** · Kurzgesagt
+>
+> **Вердикт: Дивитися** · Оцінка: 5/5 ★★★★★
+>
+> **Про що:** як вірус кору обходить імунну систему і чому щеплення важливі для колективного імунітету.
+> **Ключові ідеї та факти:** 10 пунктів із цифрами · **Що нового** · **Обґрунтованість:** рівень доказів,
+> на що спирається автор, сумнівні твердження · **Скільки «води»:** ~10%, з позначками часу · **Для кого** ·
+> **Чому такий вердикт**
+
+Вердикти: *Дивитися / Читати*, *Переглянути частину* (які саме фрагменти), *Достатньо конспекту*, *Пропустити*.
+Шкала оцінок навмисно сувора: звичайний матеріал отримує 3, ненаукове — «Пропустити».
+
+Далі — для кожного списку:
+
+- **Сортування за темами** — ваші теми, кошики «важливо / решта» або дерево тем, яке запропонує модель;
+  нотатки переносяться в теки тем лише після попереднього перегляду.
+- **Індекс списку** — найкращі, усе за темами з оцінками, **групи повторів** (досить подивитися найкраще),
+  не в темі, ненаукове, сторінки з помилками.
+- **Експорт у Raindrop.io** — вкладені колекції за списками й темами, конспект — у нотатці закладки.
+
+## Встановлення
+
+Знадобиться лише [uv](https://docs.astral.sh/uv/) — невелика програма, яка сама поставить потрібний Python
+і backlog-digest окремо від решти системи. Права адміністратора не потрібні.
+
+**1. Встановіть uv** (один раз). Windows — у PowerShell:
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+macOS і Linux — у Терміналі:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+**2. Встановіть backlog-digest**, потім закрийте й знову відкрийте вікно терміналу:
+
+```bash
+uv tool install backlog-digest
+uv tool update-shell
+```
+
+**3. Запустіть:**
+
+```bash
+bdig
+```
+
+Під час першого запуску майстер за кілька хвилин усе налаштує — мову, теку для конспектів, ключ моделі,
+перше джерело, скільки на день, щоденний розклад — і одразу зробить перший конспект. Повторно: `bdig setup`.
+`bdig shortcut` — ярлик на робочому столі (програма відкривається в окремому вікні); `bdig doctor` — перевірка,
+чи все на місці.
+
+**Ключ моделі.** Найпростіше — безкоштовний ключ Google Gemini: відкрийте <https://aistudio.google.com/apikey>,
+увійдіть, «Create API key», вставте в майстрі (меню → 8 → 4). Ключі OpenRouter і DeepSeek теж підходять —
+вони запасні, коли в однієї моделі скінчився добовий ліміт.
+
+Оновлення — `uv tool upgrade backlog-digest`. Видалення — `bdig autostart off`, потім
+`uv tool uninstall backlog-digest` (конспекти лишаються у вашій теці).
+
+## Джерела
+
+### YouTube
+
+Без Google Cloud і без ключів YouTube. Меню → 2 Джерела → 1 → посилання на плейлист, канал (`@назва`) або відео.
+
+Обробка має два незалежні кроки — їх можна робити разом або окремо, у різний час:
+- **зібрати субтитри** — повільно, з вашої інтернет-адреси, моделі не потрібні. Тексти лежать у базі,
+  доки не готовий конспект, потім видаляються;
+- **зробити конспекти** із зібраного — YouTube не потрібен, швидко, скільки дозволяють ліміти моделей.
+
+Коли YouTube тимчасово обмежив вашу адресу, конспекти з уже зібраного далі робляться, а коли скінчились
+ліміти моделей — далі збираються субтитри. Між запитами субтитрів — випадкова пауза 1–3 хв і не більше
+30 запитів на добу (`[youtube] delay_min/delay_max`, `[limits] per_day` у `config.toml`). Відео без субтитрів
+отримують статус «без тексту». Те саме відео в кількох списках конспектується один раз.
+
+### Книги й документи з папки
+
+Меню → 2 → 2 → повний шлях до теки (можна синхронізовану: Google Drive, OneDrive, Dropbox). Підтеки першого
+рівня стають окремими списками.
+
+- Формати: PDF, EPUB, FB2 (і .fb2.zip), DOCX, ODT, RTF, HTML, TXT, MD — без додаткових програм;
+  DJVU — безкоштовна DjVuLibre; MOBI, AZW3, DOC — безкоштовна Calibre (`bdig doctor` покаже, чи знайдено).
+- Довга книга читається частинами: спершу робочі нотатки частин, потім підсумковий конспект; після зупинки
+  продовжується з того самого місця.
+- Скан без текстового шару отримує статус «без тексту». Перейменований чи переміщений файл не стає новим.
+
+### Веб-статті й закладки браузера
+
+Меню → 2 → 3 → по одному в рядку: посилання або шлях до файлу — HTML-експорт закладок Chrome, Edge, Firefox,
+Safari (теки стають списками), експорт Pocket (HTML, CSV), Instapaper (CSV), будь-який CSV зі стовпцем `url`
+або TXT з посиланнями.
+
+- Береться лише основний текст сторінки (без меню, реклами й коментарів), з назвою, автором і датою.
+  Посилання на PDF читається як книга, на YouTube — як відео.
+- Сторінки, якої більше немає, і сторінки без тексту (вхід, платний доступ) отримують «без тексту»;
+  тимчасові помилки сайту — повтор пізніше.
+- **Лише потрібні теки.** Після файлу закладок програма показує теки з кількістю посилань: номер — вибрати
+  (з вкладеними), `>номер` — відкрити, `<` — назад, Enter — готово. Командою: `--only "Читати/Наука"`.
+- Файл можна перезберегти з браузера — додадуться лише нові посилання.
+
+### Raindrop.io
+
+1. **Токен:** <https://app.raindrop.io/settings/integrations> → «Create new app» (назва будь-яка) →
+   відкрити створену програму → «Create test token».
+2. Меню → 2 → 4 → вставити токен (його не видно; перевіряється й зберігається у `.env`) → вибрати колекції
+   або Enter — усі закладки.
+
+Колекції стають списками («Наука/Фізика»), «Несортовані» — без списку. Програма лише читає закладки.
+
+## Сортування, індекс, експорт
+
+**Сортування за темами** (меню → 4 → список):
+- **Мої теми** — теми й підтеми пишете ви (відкривається Блокнот / TextEdit / nano; підтема — з відступом);
+- **Важливість** — кошики на зразок «Важливо, Різне» за вашим правилом словами;
+- **Авто** — модель пропонує дерево тем, його можна виправити.
+
+Можна додати критерії (зміст, цінність, глибина, обґрунтованість) і свої правила словами. Спершу —
+попередній перегляд, нотатки переносяться лише після згоди. На 40 конспектів — один запит до моделі.
+Схема запам'ятовується: нові конспекти списку розкладаються в її теми самі.
+
+**Звіт та індекс.** Одним запитом модель визначає головну тему списку, групи повторів (✅ на найкращому)
+і що не в темі. У теці списку з'являється нотатка `_Індекс — <список>.md`; після кожної обробки вона
+оновлюється сама.
+
+**Експорт у Raindrop.io** (меню → 5 або `bdig export`): окрема коренева колекція «Backlog digest», усередині —
+списки й теми. Повторний експорт надсилає лише нове й змінене. Ваші закладки не змінюються, а колекція
+експорту не імпортується назад.
+
+## Розклад
+
+Меню → 6: що робити (оновити списки → конспекти → звіт → Raindrop), скільки, щодня чи раз на тиждень,
+«не раніше ГГ:ХХ». Автозапуск — системним планувальником без прав адміністратора: Планувальник завдань Windows
+(без вікна), launchd на macOS, таймер systemd або cron на Linux. Комп'ютер був вимкнений — завдання
+наздожене при наступному ввімкненні. Паралельно не запускається; журнал — у файлі й у нотатці
+«_Журнал розкладу».
+
+## Команди
+
+Усе є в меню (`bdig`); те саме командами — зручно для скриптів:
+
+```bash
+bdig add "https://www.youtube.com/playlist?list=..." --name "Наука"   # джерело YouTube
+bdig add "D:\Книги"                                                  # тека з книгами
+bdig add bookmarks.html --only "Читати/Наука"                        # закладки, одна тека
+bdig add raindrop "Читати пізніше"                                   # колекції Raindrop
+bdig sync                     # знайти нове в усіх джерелах
+bdig process --limit 20       # зібрати тексти й зробити конспекти
+bdig fetch --limit 30         # лише зібрати субтитри
+bdig summarize                # лише конспекти із зібраного
+bdig export                   # конспекти — у Raindrop
+bdig run-jobs --force         # виконати завдання розкладу зараз
+bdig autostart on|off|status  # автозапуск розкладу
+bdig --lang fr doctor         # перевірка французькою (uk, en, fr, es)
+```
+
+Ctrl+C зупиняє будь-якої миті, наступний запуск продовжить з того самого місця.
+
+## Ваші дані — ваші
+
+- Усе працює на вашому комп'ютері; конспекти — звичайні файли Markdown у вашій теці.
+- Джерела лише читаються: у YouTube, закладках і Raindrop нічого не змінюється (експорт — в окрему колекцію).
+- Ключі — у змінних середовища або у файлі `.env` у теці налаштувань; програма ніколи не показує їхні значення.
+- Без телеметрії.
+
+| Що | Windows | macOS | Linux |
+|---|---|---|---|
+| Налаштування `config.toml` і ключі `.env` | `%APPDATA%\backlog-digest` | `~/Library/Application Support/backlog-digest` | `~/.config/backlog-digest` |
+| База, кеш, журнали | `%LOCALAPPDATA%\backlog-digest` | те саме | `~/.local/share/backlog-digest` |
+
+`BACKLOG_DIGEST_HOME=<тека>` (або `bdig --home <тека>`) кладе все в одну теку.
+
+Мова інтерфейсу (uk, en, fr, es) і мова конспектів (будь-яка) — окремі налаштування (меню → 8).
+
+## Ще
+
+- [Питання й відповіді](docs/FAQ.uk.md): ліміти, обмеження YouTube, скани, довгі шляхи Windows та інші граблі.
+- [Розробка](docs/development.md): запуск із коду, тести, будова проєкту.
+- [Технічне завдання](docs/ТЗ.md).
+
+Виріс з особистого інструмента автора `yt-digest`, яким автор щодня робить конспекти відео.