newswatcher 0.1.0__tar.gz

newswatcher-0.1.0/.agents/plugins/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "newswatcher",
+  "interface": { "displayName": "newswatcher" },
+  "plugins": [
+    {
+      "name": "newswatcher",
+      "source": { "source": "local", "path": "./plugins/newswatcher" },
+      "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
+      "category": "Productivity"
+    }
+  ]
+}

newswatcher-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,13 @@
+{
+  "name": "newswatcher",
+  "owner": {
+    "name": "seokhoonj"
+  },
+  "plugins": [
+    {
+      "name": "newswatcher",
+      "source": "./plugins/newswatcher",
+      "description": "Run a newswatcher poll from a Claude Code conversation: collect new articles from your feeds, summarize them with an LLM, and deliver the topic digest by email or chat. Calls the newswatcher package's CLI."
+    }
+  ]
+}

newswatcher-0.1.0/.gitattributes

@@ -0,0 +1,11 @@
+# Normalize line endings: text files are stored as LF in the repository no
+# matter which machine commits. This repo's .git is shared across a Linux box
+# and a Windows box (via Dropbox), so without this the Windows CRLF working
+# tree shows up as whole-file phantom diffs on Linux. Binary files are left
+# untouched by git's own detection.
+#
+# `eol=lf` makes the *working tree* LF too, and it is not tidiness here: Dropbox
+# syncs the checked-out files, not the index, so a CRLF checkout on Windows is
+# what the Linux box then opens. `text=auto` alone left the two boxes disagreeing
+# about every line of every file either had written.
+* text=auto eol=lf

newswatcher-0.1.0/.github/workflows/check.yml

@@ -0,0 +1,24 @@
+name: check
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+  pull_request:
+
+# A newer push to the same branch or PR makes the older run's result obsolete,
+# so cancel it rather than let both run to completion.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+# The check only reads the code to lint, type, and test it -- it never writes to the
+# repo -- so it runs with the least privilege that still allows a checkout.
+permissions:
+  contents: read
+
+jobs:
+  check:
+    # The full check lives in reusable-check.yml so one definition serves the push / PR
+    # check and any release gate that later reuses it.
+    uses: ./.github/workflows/reusable-check.yml

newswatcher-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,61 @@
+name: publish
+
+# Publish to PyPI on a GitHub Release, via PyPI Trusted Publishing (OIDC): no API
+# token or password is stored anywhere -- GitHub mints a short-lived identity token
+# that PyPI verifies against the publisher registered for this repo (owner seokhoonj
+# / repo newswatcher / this workflow / environment "pypi").
+#
+# Three jobs. `gate` runs the same reusable check that check.yml runs, on the
+# release commit, so a red build (a lint/type error, a broken test, a lost py.typed
+# or console script) cannot reach an upload. `build` builds the sdist and wheel and
+# hands them to `publish` as an artifact. `publish` -- the only job holding the OIDC
+# token -- downloads that artifact and uploads it, and checks out no source, so the
+# privileged step runs the least code.
+
+on:
+  release:
+    types: [published]
+
+# Workflow-level floor: any job without its own `permissions:` block still gets a
+# read-only token, so a job added later cannot silently inherit a write-capable
+# default. The build and publish jobs narrow it further below.
+permissions:
+  contents: read
+
+jobs:
+  gate:
+    uses: ./.github/workflows/reusable-check.yml
+
+  build:
+    needs: gate
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - name: Build sdist and wheel, then check the metadata
+        run: |
+          uv build
+          uvx twine check dist/*
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment: pypi
+    permissions:
+      id-token: write   # OIDC; this is what replaces a stored token
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1

newswatcher-0.1.0/.github/workflows/reusable-check.yml

@@ -0,0 +1,82 @@
+name: reusable check
+
+# The full check -- tests, lint, types, and the packaging assertions -- factored into
+# one reusable job so a push / PR check and any release gate that later reuses it run
+# the *identical* thing rather than two copies that drift.
+
+on:
+  workflow_call:
+
+# The floor lives on the shared body so every caller runs the check read-only. A
+# reusable workflow can only downscope from its caller, so this never widens a token.
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        # The floor and the current release. requires-python says >=3.11, so 3.11 is the
+        # version that claim has to hold on; the upper end tracks whatever CPython ships.
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+
+      - name: Install
+        # A venv per matrix version, not `uv pip --system`: the runner's system Python
+        # is externally managed and is one fixed version whatever the matrix says. This
+        # is also what the README tells a person to run.
+        run: |
+          uv venv --python ${{ matrix.python-version }}
+          uv pip install -e . --group dev
+          .venv/bin/python -c "import sys; print('testing on', sys.version)"
+
+      - name: Test
+        run: .venv/bin/pytest -q
+
+      - name: Lint
+        run: .venv/bin/ruff check src tests
+
+      - name: Types
+        run: .venv/bin/mypy
+
+      - name: Confirm the package imports with only its declared dependencies
+        # newswatcher pulls in third-party runtime deps (feedparser, bs4, requests, ...).
+        # Installed into a bare environment with nothing but those declared deps, it must
+        # import and its CLI must run -- so an import the pyproject forgot to declare
+        # fails here rather than in a user's fresh install.
+        run: |
+          uv venv /tmp/bare --python ${{ matrix.python-version }}
+          uv pip install --python /tmp/bare/bin/python .
+          /tmp/bare/bin/python -c "import newswatcher; print('newswatcher', newswatcher.__version__, 'imports')"
+          /tmp/bare/bin/newswatcher --help > /dev/null
+
+      - name: Confirm the console script installed
+        # pyproject declares a `newswatcher` entry point; a wheel that dropped it would
+        # leave the skill and the docs pointing at a command that is not there.
+        run: |
+          uv venv /tmp/cli --python ${{ matrix.python-version }}
+          uv pip install --python /tmp/cli/bin/python .
+          /tmp/cli/bin/newswatcher --version
+
+      - name: Confirm py.typed ships in the built package
+        # The hints are invisible to a user's type checker unless py.typed rides along
+        # (PEP 561), and the source cannot answer whether the wheel kept it: the file can
+        # sit in git while the build omits it. Install the built package and look for it.
+        run: |
+          uv venv /tmp/typed --python ${{ matrix.python-version }}
+          uv pip install --python /tmp/typed/bin/python .
+          /tmp/typed/bin/python -c "
+          import importlib.util, pathlib
+          spec = importlib.util.find_spec('newswatcher')
+          root = pathlib.Path(spec.origin).parent
+          assert (root / 'py.typed').is_file(), 'py.typed missing from the installed package'
+          print('py.typed ships alongside newswatcher')
+          "

newswatcher-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+
+# uv
+uv.lock
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Local scratch (never tracked)
+dev/
+refs/
+
+# AI coding agents
+CLAUDE.md
+.claude/
+AGENTS.md
+AGENT.md
+.codex/
+GEMINI.md
+.gemini/
+
+docs/superpowers/

newswatcher-0.1.0/LICENSE

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

newswatcher-0.1.0/Makefile

@@ -0,0 +1,13 @@
+# Run the standard CI checks (test, lint, types) locally. Dev extras: uv pip install -e ".[dev]"
+.PHONY: check test lint types
+
+check: test lint types
+
+test:
+	pytest -q
+
+lint:
+	ruff check src tests
+
+types:
+	mypy

newswatcher-0.1.0/PKG-INFO

@@ -0,0 +1,367 @@
+Metadata-Version: 2.4
+Name: newswatcher
+Version: 0.1.0
+Summary: Collect topic-matched articles from RSS and robots-permitted crawl sources, summarize them, and mail a digest.
+Project-URL: Homepage, https://github.com/seokhoonj/newswatcher
+Project-URL: Repository, https://github.com/seokhoonj/newswatcher
+Project-URL: Issues, https://github.com/seokhoonj/newswatcher/issues
+Author-email: Seokhoon Joo <seokhoonj@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: crawl,digest,email,news,rss,topics,watch
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Internet
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: credbox<0.5,>=0.4.0
+Requires-Dist: feedparser>=6.0
+Requires-Dist: lxml>=5.0
+Requires-Dist: requests>=2.31
+Requires-Dist: soupsieve>=2.4
+Requires-Dist: thinchat<0.4,>=0.3.1
+Requires-Dist: trafilatura>=1.8
+Provides-Extra: all
+Requires-Dist: mailmail>=0.4.2; extra == 'all'
+Requires-Dist: pushpush>=0.3.1; extra == 'all'
+Provides-Extra: chat
+Requires-Dist: pushpush>=0.3.1; extra == 'chat'
+Provides-Extra: email
+Requires-Dist: mailmail>=0.4.2; extra == 'email'
+Description-Content-Type: text/markdown
+
+# newswatcher
+
+[![check](https://github.com/seokhoonj/newswatcher/actions/workflows/check.yml/badge.svg)](https://github.com/seokhoonj/newswatcher/actions/workflows/check.yml)
+[![PyPI](https://img.shields.io/pypi/v/newswatcher)](https://pypi.org/project/newswatcher/)
+[![Python](https://img.shields.io/pypi/pyversions/newswatcher)](https://pypi.org/project/newswatcher/)
+[![License](https://img.shields.io/pypi/l/newswatcher)](https://github.com/seokhoonj/newswatcher/blob/main/LICENSE)
+
+**English** | [한국어](README.ko.md)
+
+newswatcher watches RSS feeds and robots-permitted listing pages, matches new
+articles against topics you define, summarizes the matches with an LLM, and
+sends one topic-grouped digest by email, chat, or both. Delivery is optional — the
+core collects, summarizes, and archives on its own; email and chat are opt-in add-ons
+(`newswatcher[email]` / `newswatcher[chat]`). Several outlets covering the same story
+collapse into a single entry. The topics are yours to define, so
+the same tool tracks a stock ticker, a technology, a policy beat, or any subject
+a feed covers.
+
+## 1. Install
+
+newswatcher requires Python 3.11 or newer. The core — collect, summarize, archive — installs on
+its own; delivery is opt-in, so add the channel you want:
+
+```sh
+pip install newswatcher            # core: collect, summarize, archive (read with `articles`)
+pip install "newswatcher[email]"   # + email digests, via mailmail
+pip install "newswatcher[chat]"    # + chat digests, via pushpush
+pip install "newswatcher[all]"     # + both
+```
+
+The Quickstart below needs only the core `newswatcher` — email and chat come later (Delivery).
+
+## 2. Quickstart
+
+These are terminal commands (a shell — Terminal, PowerShell, or Command Prompt — not the
+Python prompt). First get a free Gemini API key from
+[Google AI Studio](https://aistudio.google.com/apikey) (sign in with Google, click **Create
+API key**, copy it), then store it — you are prompted, and the key is not echoed:
+
+```sh
+newswatcher set-key gemini
+```
+
+Define a topic, register an RSS source, run one pass, and read the summaries — no email setup
+needed to get a first result:
+
+```sh
+newswatcher add-topic markets --include stocks Fed "interest rate" earnings --exclude sports
+newswatcher add-source korea-herald "https://www.koreaherald.com/rss/newsAll" --kind rss --topic markets
+newswatcher poll --no-mail
+newswatcher articles
+```
+
+If `articles` shows nothing, the poll just matched no new articles yet — that is normal, not an
+error; broaden the `--include` keywords or run `poll` again later.
+
+A topic matches on the feed's own language, so pair the keywords with the feed: English
+keywords for an English feed, Korean keywords for a Korean feed. `newswatcher topics` and
+`newswatcher sources` show what you registered.
+
+To have the digest **emailed** or sent to **chat** instead of read with `articles`, install the
+delivery extra and configure the channel once — see [Delivery](#4-delivery).
+
+## 3. Commands
+
+Run `newswatcher --help` or `newswatcher <command> --help` for every option;
+`newswatcher --version` prints the version.
+
+| Command | What it does |
+|---------|--------------|
+| `add-topic <name> [--include WORD...] [--exclude WORD...]` | Define a topic filter: a name, `--include` keywords (an article matches when it has any one of them), and optional `--exclude` keywords (any one rejects it). Empty includes match every article. |
+| `topics` | List the defined topics with their include / exclude keywords. |
+| `add-source <name> <url> [--kind rss\|crawl] [--topic NAME]... [--keep-all]` | Register a source — an RSS feed (`--kind rss`) or a robots-permitted crawl page (`--kind crawl`) — and the `--topic`s to test it against. A crawl source also needs selectors: `--item --title --link` (required), `--date --body-selector` (optional). `--keep-all` keeps every article from the source without keyword filtering (for a trade feed that is wholly on-topic). |
+| `sources` | List the registered sources with their kind, URL, and topics. |
+| `set-key <provider>` | Store an LLM provider's API key with thinchat, prompted without echo (in thinchat's own credential store). The provider is `gemini`, `openai`, or `claude`; the key is also read from the matching `*_API_KEY` environment variable, which takes precedence. |
+| `setup [--provider P]` | Fill in the missing secrets for every channel in one guided pass — the LLM key with thinchat, each email password with mailmail, each chat token with pushpush — prompting without echo and printing where each landed. Skips what is already set, and points you at the tool to configure a channel that has no account or route yet. |
+| `doctor [--provider P]` | Show where each secret and config file lives and whether it is set, without printing any secret. Exits non-zero when a configured channel is missing its secret or its store is unreadable, so a scheduled run can gate on a complete setup. |
+| `recent <url> [--limit N]` | Fetch and print a feed's latest items (title + link) without storing or summarizing — a quick check of a URL before you register it. `--limit N` caps how many. |
+| `poll` | Run one pass: fetch every source, keep the new articles that match a topic, summarize them, archive them, and send the digest. `--to` / `--push` set destinations; `--no-mail` collects without sending; `--no-store` skips archiving; `--no-heal` skips selector repair; `--provider` / `--model` choose the LLM. |
+| `watch [--every N]` | Run `poll` repeatedly in the foreground, every `--every` minutes (default 30), until you stop it. Takes all of `poll`'s options. |
+| `articles [--topic NAME] [--since DATE] [--until DATE]` | List archived articles (title, our summary, link), optionally narrowed to a topic and a half-open `[since, until)` date range. |
+| `heal [--dry-run] [--provider P] [--model M]` | Check crawl sources whose selectors stopped matching and repair them with an LLM, validated against the live page. `--dry-run` reports the proposed fix without writing it. |
+| `schedule install\|status\|remove [--every N]` | Install, show, or remove the recurring poll in the OS scheduler (cron on Linux/macOS, schtasks on Windows). `--every N` sets the interval. |
+
+## 4. Delivery
+
+The digest is sent by email, to a chat channel, or both — set one or both destinations.
+Each channel is an opt-in extra (`newswatcher[email]` / `newswatcher[chat]`); its companion
+package keeps its own credentials, so newswatcher never stores your email password or bot token.
+Without either extra, newswatcher still collects, summarizes, and archives — read the archive with
+`newswatcher articles`.
+
+- Email goes through the mailmail package (`newswatcher[email]`). Set up an account (or an
+  address-book alias) once with mailmail's own CLI (`mailmail --help`); then `--to ADDRESS`, or the
+  `NEWSWATCHER_DIGEST_TO` setting, names that alias or a plain address.
+- Chat goes through the pushpush package (`newswatcher[chat]`). Configure a route (a bot plus its
+  destination — Telegram, Slack, or Discord) once with pushpush's own CLI (`pushpush --help`); then
+  `--push ROUTE`, or the `NEWSWATCHER_DIGEST_PUSH` setting, names that route. The digest is sent as
+  one markdown message.
+
+So newswatcher holds no secret of its own: the LLM key lives with thinchat, the email password
+with mailmail, the chat token with pushpush — each in its own store, exactly as when the tool is
+used on its own. Configure them all in one guided pass with `newswatcher setup`, and see the full
+map — what is set and where it lives — with `newswatcher doctor`.
+
+## 5. News feeds
+
+Any valid RSS/Atom feed works as a source. A representative set of verified
+Korean feeds is below; the full list, grouped by section and marked with which
+were live at verification, is in [docs/korean-news-rss.md](docs/korean-news-rss.md).
+A site with no feed can still be followed with a `--kind crawl` source.
+
+| Outlet | Beat | Feed URL |
+|--------|------|----------|
+| 연합뉴스 (Yonhap) | wire | `https://www.yna.co.kr/rss/news.xml` |
+| 한국경제 (Hankyung) | economy | `https://www.hankyung.com/feed/all-news` |
+| 조선비즈 (ChosunBiz) | economy | `https://biz.chosun.com/arc/outboundfeeds/rss/?outputType=xml` |
+| 매일경제 (Maeil) | economy | `https://www.mk.co.kr/rss/30000001/` |
+| 이데일리 (Edaily) | economy | `http://rss.edaily.co.kr/edaily_news.xml` |
+| 머니투데이 (MoneyToday) | economy | `http://rss.mt.co.kr/mt_news.xml` |
+| 전자신문 (ETNews) | tech | `https://rss.etnews.com/Section901.xml` |
+| 지디넷코리아 (ZDNet Korea) | tech | `https://feeds.feedburner.com/zdkorea` |
+| The Korea Herald | English | `https://www.koreaherald.com/rss/newsAll` |
+| The Korea Times | English | `https://feed.koreatimes.co.kr/k/allnews.xml` |
+
+A representative set of verified international (English) feeds is below; the full
+list, grouped by category and marked with which outlets paywall the article body,
+is in [docs/world-news-rss.md](docs/world-news-rss.md). Pair these with English
+topic keywords.
+
+| Outlet | Beat | Feed URL |
+|--------|------|----------|
+| BBC News | wire | `https://feeds.bbci.co.uk/news/world/rss.xml` |
+| The Guardian | wire | `https://www.theguardian.com/world/rss` |
+| Al Jazeera | wire | `https://www.aljazeera.com/xml/rss/all.xml` |
+| The New York Times | world | `https://rss.nytimes.com/services/xml/rss/nyt/World.xml` |
+| CNBC | economy | `https://www.cnbc.com/id/100003114/device/rss/rss.html` |
+| MarketWatch | economy | `http://feeds.marketwatch.com/marketwatch/topstories/` |
+| TechCrunch | tech | `https://techcrunch.com/feed/` |
+| The Verge | tech | `https://www.theverge.com/rss/index.xml` |
+| Nature | science | `https://www.nature.com/nature.rss` |
+
+## 6. Configuration files
+
+newswatcher stores hand-edited configuration under
+`$XDG_CONFIG_HOME/newswatcher`, or `~/.config/newswatcher` when
+`XDG_CONFIG_HOME` is unset. The CLI writes the same files, so CLI and manual
+configuration can be mixed.
+
+`topics.toml` contains topic filters. An article matches when its title or feed
+summary contains any include keyword and no exclude keyword. An empty
+`includes` list matches every article.
+
+```toml
+[[topic]]
+name = "markets"
+includes = ["stocks", "Fed", "interest rate", "earnings"]
+excludes = ["sports"]
+
+[[topic]]
+name = "semiconductors"
+includes = ["chip", "foundry", "HBM", "TSMC", "Nvidia"]
+```
+
+`sources.toml` contains RSS or crawl sources. `topics` selects the topic filters
+applied to a source. Set `keep_all = true` for a source whose every article
+should be retained without keyword filtering.
+
+```toml
+[[source]]
+name = "korea-herald"
+kind = "rss"
+url = "https://www.koreaherald.com/rss/newsAll"
+topics = ["markets", "semiconductors"]
+
+[[source]]
+name = "exchange-notices"
+kind = "crawl"
+url = "https://example.com/markets/notices"
+topics = ["markets"]
+item = "article.news-item"
+title = "h2"
+link = "a@href"
+date = "time"
+body_selector = "main article"
+```
+
+The `item`, `title`, and `link` selectors are required for crawl sources;
+`date` and `body_selector` are optional. The link selector uses the
+`css@attribute` form when the URL is stored in an attribute.
+
+Non-secret settings can also be placed in `config.toml`. Environment variables
+take precedence over corresponding settings there. For example,
+`NEWSWATCHER_DIGEST_TO` maps to `digest_to`, and `NEWSWATCHER_DIGEST_PUSH` to `digest_push`.
+`NEWSWATCHER_DEDUP_THRESHOLD` (`dedup_threshold`, 0.0–1.0, default 0.5) sets how alike two
+headlines must be to collapse as one story — raise it to merge less, lower it to merge
+more. The article archive and run state use
+the XDG data and state directories; `NEWSWATCHER_DATA_DIR` and
+`NEWSWATCHER_STATE_DIR` can override them. The archive deletes nothing by default; to
+prune old records, set `NEWSWATCHER_ARCHIVE_KEEP_DAYS` (`archive_keep_days`, a positive
+integer) and each poll removes archived articles older than that after the digest is
+sent. Leaving it unset keeps everything (this deletion is irreversible, so enable it
+deliberately).
+
+## 7. Provider keys and model
+
+A **provider** is the LLM service that writes the summaries. newswatcher supports four; pass the
+name in the left column to `--provider` or `set-key`:
+
+| Provider | Key (environment variable) | Where to get a key |
+|----------|----------------------------|--------------------|
+| `gemini` (default) | `GEMINI_API_KEY` | [Google AI Studio](https://aistudio.google.com/apikey) — free tier |
+| `openai` | `OPENAI_API_KEY` | [platform.openai.com](https://platform.openai.com/api-keys) |
+| `claude` | `CLAUDE_API_KEY` | [console.anthropic.com](https://console.anthropic.com/settings/keys) |
+| `ollama` | — (runs locally) | no key needed |
+
+The provider key is a secret, and it lives with thinchat — the library newswatcher
+summarizes through — not with newswatcher. Store it once with `setup` (which configures
+email and chat in the same pass) or with `set-key` for the key alone; both prompt without
+echoing and write to thinchat's own credential store:
+
+```sh
+newswatcher setup            # the LLM key, plus email and chat, in one pass
+newswatcher set-key gemini   # just the LLM key
+```
+
+Each key is also read from its environment variable (the table above), which takes precedence,
+so a one-off run can supply a key without storing anything.
+
+newswatcher summarizes with Gemini's free tier by default. Choose another provider,
+and optionally a specific model, with `--provider` / `--model`, or persistently
+with the `NEWSWATCHER_LLM_PROVIDER` / `NEWSWATCHER_LLM_MODEL` settings (`llm_provider`
+and `llm_model` in `config.toml`):
+
+```sh
+newswatcher poll --provider claude --model claude-sonnet-5
+export NEWSWATCHER_LLM_PROVIDER=openai
+```
+
+## 8. Responsible collection
+
+Every feed, listing-page, and article request is checked against the site's
+robots policy before it is sent, and newswatcher identifies itself with its user
+agent. A disallowed URL is not fetched. The durable archive and outbound digest
+contain the LLM-written summary, source link, and metadata only. Raw article
+bodies are transient summary input and are neither archived nor sent.
+
+## 9. Scheduling
+
+Install a recurring poll every 30 minutes:
+
+```sh
+newswatcher schedule install
+```
+
+Choose another interval with minutes, `Nm`, or `Nh`, and inspect or remove the
+job as needed:
+
+```sh
+newswatcher schedule install --every 2h
+newswatcher schedule status
+newswatcher schedule remove
+```
+
+Scheduling uses `crontab` on Linux and macOS and `schtasks` on Windows. On Windows
+any interval under a day works (`--every 45`, `--every 5h`); on Linux and macOS cron
+only fires intervals that divide evenly (15/20/30 min, 1/2/4/8/12 h, or daily) and
+rejects the rest rather than mis-scheduling them. The scheduled process uses the same
+configuration as an interactive poll, so make sure the LLM key is reachable (from
+thinchat's store or its environment variable) along with any settings not stored
+in `config.toml`. `newswatcher doctor` confirms it before you schedule.
+
+On Windows the task is registered under the installing user and runs in their
+interactive session, so it does not fire while nobody is signed in — a locked screen is
+fine, a machine sitting at the sign-in screen is not. It also inherits the Task Scheduler
+default of not starting on battery power. Check it with
+`schtasks /Query /TN newswatcher-poll`. On Linux and macOS the cron job has neither
+restriction.
+
+A poll takes a single-instance lock, so a scheduled poll and a manual one never run
+at once — whichever starts second logs that a poll is already running and exits. The
+lock uses `flock` on Linux and macOS and `msvcrt` on Windows.
+
+## 10. Use it from an AI coding agent
+
+This repo ships a `poll` skill: ask in plain words ("run my newswatcher poll", "check the
+news") and it runs one poll and relays what it found.
+
+### Claude Code
+
+In the Claude Code chat, add the marketplace and install:
+
+```
+/plugin marketplace add seokhoonj/newswatcher
+/plugin install newswatcher@newswatcher
+```
+
+Then invoke it with `/newswatcher:poll`, or just ask in plain language. The skill calls the
+`newswatcher` command, so install the package too (`pip install newswatcher`). See
+`plugins/newswatcher/skills/poll/SKILL.md`.
+
+### Codex
+
+In your terminal, add the marketplace and install:
+
+```
+codex plugin marketplace add seokhoonj/newswatcher
+codex plugin add newswatcher@newswatcher
+```
+
+The `poll` skill responds automatically to matching requests.
+
+### By hand (symlink)
+
+Symlink the skill into your skills directory and call it as `/poll`:
+
+```sh
+ln -s "$PWD/plugins/newswatcher/skills/poll" ~/.claude/skills/poll   # Claude Code -> /poll
+ln -s "$PWD/plugins/newswatcher/skills/poll" ~/.codex/skills/poll    # Codex -> $newswatcher:poll
+```
+
+Claude Code picks it up immediately; Codex needs a restart to load it.
+
+## 11. License
+
+[MIT](LICENSE)