better-dsh 0.2.5 → 0.3.0-a

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/research/research-arxiv.md

@@ -1,300 +0,0 @@
----
-title: "Arxiv — Search arXiv papers by keyword, author, category, or ID"
-sidebar_label: "Arxiv"
-description: "Search arXiv papers by keyword, author, category, or ID"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Arxiv
-
-Search arXiv papers by keyword, author, category, or ID.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Bundled (installed by default) |
-| Path | `skills/research\arxiv` |
-| Version | `1.0.0` |
-| Author | Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `Research`, `Arxiv`, `Papers`, `Academic`, `Science`, `API` |
-| Related skills | `ocr-and-documents` |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# arXiv Research
-
-Search and retrieve academic papers from arXiv via their free REST API. No API key, no dependencies — just curl.
-
-## Quick Reference
-
-| Action | Command |
-|--------|---------|
-| Search papers | `curl "https://export.arxiv.org/api/query?search_query=all:QUERY&max_results=5"` |
-| Get specific paper | `curl "https://export.arxiv.org/api/query?id_list=2402.03300"` |
-| Read abstract (web) | `web_extract(urls=["https://arxiv.org/abs/2402.03300"])` |
-| Read full paper (PDF) | `web_extract(urls=["https://arxiv.org/pdf/2402.03300"])` |
-
-## Searching Papers
-
-The API returns Atom XML. Parse with `grep`/`sed` or pipe through `python` for clean output.
-
-### Basic search
-
-```bash
-curl -s "https://export.arxiv.org/api/query?search_query=all:GRPO+reinforcement+learning&max_results=5"
-```
-
-### Clean output (parse XML to readable format)
-
-```bash
-curl -s "https://export.arxiv.org/api/query?search_query=all:GRPO+reinforcement+learning&max_results=5&sortBy=submittedDate&sortOrder=descending" | python -c "
-import sys, xml.etree.ElementTree as ET
-ns = {'a': 'http://www.w3.org/2005/Atom'}
-root = ET.parse(sys.stdin).getroot()
-for i, entry in enumerate(root.findall('a:entry', ns)):
-    title = entry.find('a:title', ns).text.strip().replace('\n', ' ')
-    arxiv_id = entry.find('a:id', ns).text.strip().split('/abs/')[-1]
-    published = entry.find('a:published', ns).text[:10]
-    authors = ', '.join(a.find('a:name', ns).text for a in entry.findall('a:author', ns))
-    summary = entry.find('a:summary', ns).text.strip()[:200]
-    cats = ', '.join(c.get('term') for c in entry.findall('a:category', ns))
-    print(f'{i+1}. [{arxiv_id}] {title}')
-    print(f'   Authors: {authors}')
-    print(f'   Published: {published} | Categories: {cats}')
-    print(f'   Abstract: {summary}...')
-    print(f'   PDF: https://arxiv.org/pdf/{arxiv_id}')
-    print()
-"
-```
-
-## Search Query Syntax
-
-| Prefix | Searches | Example |
-|--------|----------|---------|
-| `all:` | All fields | `all:transformer+attention` |
-| `ti:` | Title | `ti:large+language+models` |
-| `au:` | Author | `au:vaswani` |
-| `abs:` | Abstract | `abs:reinforcement+learning` |
-| `cat:` | Category | `cat:cs.AI` |
-| `co:` | Comment | `co:accepted+NeurIPS` |
-
-### Boolean operators
-
-```
-# AND (default when using +)
-search_query=all:transformer+attention
-
-# OR
-search_query=all:GPT+OR+all:BERT
-
-# AND NOT
-search_query=all:language+model+ANDNOT+all:vision
-
-# Exact phrase
-search_query=ti:"chain+of+thought"
-
-# Combined
-search_query=au:hinton+AND+cat:cs.LG
-```
-
-## Sort and Pagination
-
-| Parameter | Options |
-|-----------|---------|
-| `sortBy` | `relevance`, `lastUpdatedDate`, `submittedDate` |
-| `sortOrder` | `ascending`, `descending` |
-| `start` | Result offset (0-based) |
-| `max_results` | Number of results (default 10, max 30000) |
-
-```bash
-# Latest 10 papers in cs.AI
-curl -s "https://export.arxiv.org/api/query?search_query=cat:cs.AI&sortBy=submittedDate&sortOrder=descending&max_results=10"
-```
-
-## Fetching Specific Papers
-
-```bash
-# By arXiv ID
-curl -s "https://export.arxiv.org/api/query?id_list=2402.03300"
-
-# Multiple papers
-curl -s "https://export.arxiv.org/api/query?id_list=2402.03300,2401.12345,2403.00001"
-```
-
-## BibTeX Generation
-
-After fetching metadata for a paper, generate a BibTeX entry:
-
-{% raw %}
-```bash
-curl -s "https://export.arxiv.org/api/query?id_list=1706.03762" | python -c "
-import sys, xml.etree.ElementTree as ET
-ns = {'a': 'http://www.w3.org/2005/Atom', 'arxiv': 'http://arxiv.org/schemas/atom'}
-root = ET.parse(sys.stdin).getroot()
-entry = root.find('a:entry', ns)
-if entry is None: sys.exit('Paper not found')
-title = entry.find('a:title', ns).text.strip().replace('\n', ' ')
-authors = ' and '.join(a.find('a:name', ns).text for a in entry.findall('a:author', ns))
-year = entry.find('a:published', ns).text[:4]
-raw_id = entry.find('a:id', ns).text.strip().split('/abs/')[-1]
-cat = entry.find('arxiv:primary_category', ns)
-primary = cat.get('term') if cat is not None else 'cs.LG'
-last_name = entry.find('a:author', ns).find('a:name', ns).text.split()[-1]
-print(f'@article{{{last_name}{year}_{raw_id.replace(\".\", \"\")},')
-print(f'  title     = {{{title}}},')
-print(f'  author    = {{{authors}}},')
-print(f'  year      = {{{year}}},')
-print(f'  eprint    = {{{raw_id}}},')
-print(f'  archivePrefix = {{arXiv}},')
-print(f'  primaryClass  = {{{primary}}},')
-print(f'  url       = {{https://arxiv.org/abs/{raw_id}}}')
-print('}')
-"
-```
-{% endraw %}
-
-## Reading Paper Content
-
-After finding a paper, read it:
-
-```
-# Abstract page (fast, metadata + abstract)
-web_extract(urls=["https://arxiv.org/abs/2402.03300"])
-
-# Full paper (PDF → markdown via Firecrawl)
-web_extract(urls=["https://arxiv.org/pdf/2402.03300"])
-```
-
-For local PDF processing, see the `ocr-and-documents` skill.
-
-## Common Categories
-
-| Category | Field |
-|----------|-------|
-| `cs.AI` | Artificial Intelligence |
-| `cs.CL` | Computation and Language (NLP) |
-| `cs.CV` | Computer Vision |
-| `cs.LG` | Machine Learning |
-| `cs.CR` | Cryptography and Security |
-| `stat.ML` | Machine Learning (Statistics) |
-| `math.OC` | Optimization and Control |
-| `physics.comp-ph` | Computational Physics |
-
-Full list: https://arxiv.org/category_taxonomy
-
-## Helper Script
-
-The `scripts/search_arxiv.py` script handles XML parsing and provides clean output:
-
-```bash
-python scripts/search_arxiv.py "GRPO reinforcement learning"
-python scripts/search_arxiv.py "transformer attention" --max 10 --sort date
-python scripts/search_arxiv.py --author "Yann LeCun" --max 5
-python scripts/search_arxiv.py --category cs.AI --sort date
-python scripts/search_arxiv.py --id 2402.03300
-python scripts/search_arxiv.py --id 2402.03300,2401.12345
-```
-
-No dependencies — uses only Python stdlib.
-
----
-
-## Semantic Scholar (Citations, Related Papers, Author Profiles)
-
-arXiv doesn't provide citation data or recommendations. Use the **Semantic Scholar API** for that — free, no key needed for basic use (1 req/sec), returns JSON.
-
-### Get paper details + citations
-
-```bash
-# By arXiv ID
-curl -s "https://api.semanticscholar.org/graph/v1/paper/arXiv:2402.03300?fields=title,authors,citationCount,referenceCount,influentialCitationCount,year,abstract" | python -m json.tool
-
-# By Semantic Scholar paper ID or DOI
-curl -s "https://api.semanticscholar.org/graph/v1/paper/DOI:10.1234/example?fields=title,citationCount"
-```
-
-### Get citations OF a paper (who cited it)
-
-```bash
-curl -s "https://api.semanticscholar.org/graph/v1/paper/arXiv:2402.03300/citations?fields=title,authors,year,citationCount&limit=10" | python -m json.tool
-```
-
-### Get references FROM a paper (what it cites)
-
-```bash
-curl -s "https://api.semanticscholar.org/graph/v1/paper/arXiv:2402.03300/references?fields=title,authors,year,citationCount&limit=10" | python -m json.tool
-```
-
-### Search papers (alternative to arXiv search, returns JSON)
-
-```bash
-curl -s "https://api.semanticscholar.org/graph/v1/paper/search?query=GRPO+reinforcement+learning&limit=5&fields=title,authors,year,citationCount,externalIds" | python -m json.tool
-```
-
-### Get paper recommendations
-
-```bash
-curl -s -X POST "https://api.semanticscholar.org/recommendations/v1/papers/" \
-  -H "Content-Type: application/json" \
-  -d '{"positivePaperIds": ["arXiv:2402.03300"], "negativePaperIds": []}' | python -m json.tool
-```
-
-### Author profile
-
-```bash
-curl -s "https://api.semanticscholar.org/graph/v1/author/search?query=Yann+LeCun&fields=name,hIndex,citationCount,paperCount" | python -m json.tool
-```
-
-### Useful Semantic Scholar fields
-
-`title`, `authors`, `year`, `abstract`, `citationCount`, `referenceCount`, `influentialCitationCount`, `isOpenAccess`, `openAccessPdf`, `fieldsOfStudy`, `publicationVenue`, `externalIds` (contains arXiv ID, DOI, etc.)
-
----
-
-## Complete Research Workflow
-
-1. **Discover**: `python scripts/search_arxiv.py "your topic" --sort date --max 10`
-2. **Assess impact**: `curl -s "https://api.semanticscholar.org/graph/v1/paper/arXiv:ID?fields=citationCount,influentialCitationCount"`
-3. **Read abstract**: `web_extract(urls=["https://arxiv.org/abs/ID"])`
-4. **Read full paper**: `web_extract(urls=["https://arxiv.org/pdf/ID"])`
-5. **Find related work**: `curl -s "https://api.semanticscholar.org/graph/v1/paper/arXiv:ID/references?fields=title,citationCount&limit=20"`
-6. **Get recommendations**: POST to Semantic Scholar recommendations endpoint
-7. **Track authors**: `curl -s "https://api.semanticscholar.org/graph/v1/author/search?query=NAME"`
-
-## Rate Limits
-
-| API | Rate | Auth |
-|-----|------|------|
-| arXiv | ~1 req / 3 seconds | None needed |
-| Semantic Scholar | 1 req / second | None (100/sec with API key) |
-
-## Notes
-
-- arXiv returns Atom XML — use the helper script or parsing snippet for clean output
-- Semantic Scholar returns JSON — pipe through `python -m json.tool` for readability
-- arXiv IDs: old format (`hep-th/0601001`) vs new (`2402.03300`)
-- PDF: `https://arxiv.org/pdf/{id}` — Abstract: `https://arxiv.org/abs/{id}`
-- HTML (when available): `https://arxiv.org/html/{id}`
-- For local PDF processing, see the `ocr-and-documents` skill
-
-## ID Versioning
-
-- `arxiv.org/abs/1706.03762` always resolves to the **latest** version
-- `arxiv.org/abs/1706.03762v1` points to a **specific** immutable version
-- When generating citations, preserve the version suffix you actually read to prevent citation drift (a later version may substantially change content)
-- The API `<id>` field returns the versioned URL (e.g., `http://arxiv.org/abs/1706.03762v7`)
-
-## Withdrawn Papers
-
-Papers can be withdrawn after submission. When this happens:
-- The `<summary>` field contains a withdrawal notice (look for "withdrawn" or "retracted")
-- Metadata fields may be incomplete
-- Always check the summary before treating a result as a valid paper

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/research/research-blocked-page-recovery.md

@@ -1,155 +0,0 @@
----
-title: "Blocked Page Recovery — Recover blocked/paywalled/WAF'd pages via archive snapshots and reader fallbacks"
-sidebar_label: "Blocked Page Recovery"
-description: "Recover blocked/paywalled/WAF'd pages via archive snapshots and reader fallbacks"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Blocked Page Recovery
-
-Recover blocked/paywalled/WAF'd pages via archive snapshots and reader fallbacks. Use when web_extract or the browser hits 403/429/challenge pages, paywalls, or bot-detection interstitials.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Bundled (installed by default) |
-| Path | `skills/research/blocked-page-recovery` |
-| Version | `1.0.0` |
-| Author | Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `Research`, `Archives`, `Wayback`, `Paywall`, `WAF`, `Fallback` |
-| Related skills | [`grounded-citations`](/docs/user-guide/skills/bundled/research/research-grounded-citations) |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Blocked-Page Recovery
-
-When a page won't fetch — 403/429, Cloudflare "Just a moment...", a paywall,
-or a bot-detection interstitial — don't give up and don't loop on the same
-URL. Third-party services often hold a **copy** of the page. Work down this
-ladder, cheapest first.
-
-## The ladder
-
-```
-1. Wayback Machine  — archive.org "available" API  (snapshot + timestamp)
-2. archive.today    — domain rotation: archive.ph → .md → .li → .is
-3. Jina Reader      — only if JINA_API_KEY is set  (live server-side render)
-4. API-first pivot  — look for /api/, /graphql, .json, or RSS on the same host
-5. Real browser     — browser tool as the last, most expensive resort
-```
-
-Run it in one shot with the bundled script:
-
-```bash
-python3 scripts/recover_page.py "https://example.com/blocked-article" --json
-```
-
-The script tries each route in order, validates every body (see "Fake
-successes" below), and prints the first genuine hit with its provenance.
-
-## Provenance discipline (non-negotiable)
-
-Every recovered copy carries a provenance you MUST preserve when citing:
-
-| Route | Provenance | How to cite |
-|-------|-----------|-------------|
-| Wayback / archive.today | `snapshot` | Cite WITH the snapshot date: "as archived 2026-08-06". Never present a snapshot as the live page — it may be stale. |
-| Jina Reader | `live` | Server-side re-render of the live page; cite normally. |
-| Live fetch / browser | `live` | Cite normally. |
-
-If the user needs *current* data (prices, availability, breaking news), a
-snapshot is context, not an answer — say so explicitly and note its age.
-
-## Manual routes
-
-### 1. Wayback Machine (best provenance, try first)
-
-```bash
-# Discovery: returns closest snapshot URL + timestamp as JSON
-curl -sL "https://archive.org/wayback/available?url={URL}"
-# Then fetch archived_snapshots.closest.url
-```
-
-For enumerating many snapshots (or recovering deleted pages), the CDX index:
-
-```bash
-curl -sL "https://web.archive.org/cdx/search/cdx?url={URL}&output=json&limit=10"
-```
-
-CDX intermittently returns 503 under load — if it does, fall back to the
-`available` API; don't retry-hammer it.
-
-Works for: any publicly crawled URL. Fails for: robots-blocked sites,
-never-crawled URLs, JS-only SPAs (snapshots don't render).
-
-### 2. archive.today (paywalls, deleted content)
-
-User-submitted archives — often has paywalled news articles Wayback lacks.
-Rate-limits aggressively (429) and rotates domains, so iterate:
-
-```bash
-for d in archive.ph archive.md archive.li archive.is; do
-  curl -sL --max-time 20 "https://$d/newest/{URL}" -o /tmp/page.html \
-    -w "%{http_code}" && break
-done
-```
-
-**Validate the body, not the status code** — a 429 still ships several KB of
-rate-limit HTML that looks like a success to a size check alone.
-
-### 3. Jina Reader (requires JINA_API_KEY)
-
-`r.jina.ai` re-renders the live page in a real browser server-side and
-returns markdown. Anonymous access is dead (401 → Turnstile); a key is
-required:
-
-```bash
-curl -s -H "Authorization: Bearer $JINA_API_KEY" "https://r.jina.ai/{URL}"
-```
-
-Handles JS SPAs that archives can't. Skip this route entirely when the env
-var is unset.
-
-### 4. API-first pivot
-
-WAFs protect the HTML surface far more aggressively than the data endpoints
-behind it. After 2-3 blocked attempts on a site, stop fighting the HTML and
-look for:
-
-- `/api/...`, `/graphql`, or `.json` variants of the page URL
-- An RSS/Atom feed (`/feed`, `/rss`, `<link rel="alternate">` in any copy
-  you did recover)
-- A sitemap (`/sitemap.xml`) revealing canonical URLs that may not be gated
-
-## Fake successes — routes that LIE
-
-These return HTTP 200 with a plausible body that is NOT the page. The script
-rejects them automatically; reject them manually too:
-
-- **Google Cache is dead** (since mid-2024). `webcache.googleusercontent.com`
-  returns 200 + tens of KB, but it's a Google Search interstitial with a JS
-  redirect, not a cache. Never use it.
-- **AMP caches** (`*.cdn.ampproject.org`) mostly return a ~300-byte
-  `<title>Redirecting</title>` meta-refresh stub pointing back at the
-  original (blocked) URL. Treating that as success creates a fetch loop.
-- **Rate-limit bodies**: archive.today 429 pages are multi-KB HTML. Check for
-  the target's actual content (title words, expected strings), not just size.
-
-Detection heuristics the script applies: body under a per-route byte floor;
-meta-refresh/JS-redirect stubs whose target is the original host; interstitial
-titles ("Just a moment", "Redirecting", "Google Search", "Attention Required").
-
-## Proxy relays: don't
-
-Generic "web proxy" relays are man-in-the-middle by construction. Never send
-cookies or Authorization headers through one, and don't use them for anything
-the user will rely on — provenance is unverifiable. Prefer archives, which at
-least timestamp their copies.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/research/research-blogwatcher.md

@@ -1,152 +0,0 @@
----
-title: "Blogwatcher — Monitor blogs and RSS/Atom feeds via blogwatcher-cli tool"
-sidebar_label: "Blogwatcher"
-description: "Monitor blogs and RSS/Atom feeds via blogwatcher-cli tool"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Blogwatcher
-
-Monitor blogs and RSS/Atom feeds via blogwatcher-cli tool.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Bundled (installed by default) |
-| Path | `skills/research/blogwatcher` |
-| Version | `2.0.0` |
-| Author | JulienTant (fork of Hyaxia/blogwatcher) |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `RSS`, `Blogs`, `Feed-Reader`, `Monitoring` |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Blogwatcher
-
-Track blog and RSS/Atom feed updates with the `blogwatcher-cli` tool. Supports automatic feed discovery, HTML scraping fallback, OPML import, and read/unread article management.
-
-## Installation
-
-Pick one method:
-
-- **Go:** `go install github.com/JulienTant/blogwatcher-cli/cmd/blogwatcher-cli@latest`
-- **Docker:** `docker run --rm -v blogwatcher-cli:/data ghcr.io/julientant/blogwatcher-cli`
-- **Binary (Linux amd64):** `curl -sL https://github.com/JulienTant/blogwatcher-cli/releases/latest/download/blogwatcher-cli_linux_amd64.tar.gz | tar xz -C /usr/local/bin blogwatcher-cli`
-- **Binary (Linux arm64):** `curl -sL https://github.com/JulienTant/blogwatcher-cli/releases/latest/download/blogwatcher-cli_linux_arm64.tar.gz | tar xz -C /usr/local/bin blogwatcher-cli`
-- **Binary (macOS Apple Silicon):** `curl -sL https://github.com/JulienTant/blogwatcher-cli/releases/latest/download/blogwatcher-cli_darwin_arm64.tar.gz | tar xz -C /usr/local/bin blogwatcher-cli`
-- **Binary (macOS Intel):** `curl -sL https://github.com/JulienTant/blogwatcher-cli/releases/latest/download/blogwatcher-cli_darwin_amd64.tar.gz | tar xz -C /usr/local/bin blogwatcher-cli`
-
-All releases: https://github.com/JulienTant/blogwatcher-cli/releases
-
-### Docker with persistent storage
-
-By default the database lives at `~/.blogwatcher-cli/blogwatcher-cli.db`. In Docker this is lost on container restart. Use `BLOGWATCHER_DB` or a volume mount to persist it:
-
-```bash
-# Named volume (simplest)
-docker run --rm -v blogwatcher-cli:/data -e BLOGWATCHER_DB=/data/blogwatcher-cli.db ghcr.io/julientant/blogwatcher-cli scan
-
-# Host bind mount
-docker run --rm -v /path/on/host:/data -e BLOGWATCHER_DB=/data/blogwatcher-cli.db ghcr.io/julientant/blogwatcher-cli scan
-```
-
-### Migrating from the original blogwatcher
-
-If upgrading from `Hyaxia/blogwatcher`, move your database:
-
-```bash
-mv ~/.blogwatcher/blogwatcher.db ~/.blogwatcher-cli/blogwatcher-cli.db
-```
-
-The binary name changed from `blogwatcher` to `blogwatcher-cli`.
-
-## Common Commands
-
-### Managing blogs
-
-- Add a blog: `blogwatcher-cli add "My Blog" https://example.com`
-- Add with explicit feed: `blogwatcher-cli add "My Blog" https://example.com --feed-url https://example.com/feed.xml`
-- Add with HTML scraping: `blogwatcher-cli add "My Blog" https://example.com --scrape-selector "article h2 a"`
-- List tracked blogs: `blogwatcher-cli blogs`
-- Remove a blog: `blogwatcher-cli remove "My Blog" --yes`
-- Import from OPML: `blogwatcher-cli import subscriptions.opml`
-
-### Scanning and reading
-
-- Scan all blogs: `blogwatcher-cli scan`
-- Scan one blog: `blogwatcher-cli scan "My Blog"`
-- List unread articles: `blogwatcher-cli articles`
-- List all articles: `blogwatcher-cli articles --all`
-- Filter by blog: `blogwatcher-cli articles --blog "My Blog"`
-- Filter by category: `blogwatcher-cli articles --category "Engineering"`
-- Mark article read: `blogwatcher-cli read 1`
-- Mark article unread: `blogwatcher-cli unread 1`
-- Mark all read: `blogwatcher-cli read-all`
-- Mark all read for a blog: `blogwatcher-cli read-all --blog "My Blog" --yes`
-
-## Environment Variables
-
-All flags can be set via environment variables with the `BLOGWATCHER_` prefix:
-
-| Variable | Description |
-|---|---|
-| `BLOGWATCHER_DB` | Path to SQLite database file |
-| `BLOGWATCHER_WORKERS` | Number of concurrent scan workers (default: 8) |
-| `BLOGWATCHER_SILENT` | Only output "scan done" when scanning |
-| `BLOGWATCHER_YES` | Skip confirmation prompts |
-| `BLOGWATCHER_CATEGORY` | Default filter for articles by category |
-
-## Example Output
-
-```
-$ blogwatcher-cli blogs
-Tracked blogs (1):
-
-  xkcd
-    URL: https://xkcd.com
-    Feed: https://xkcd.com/atom.xml
-    Last scanned: 2026-04-03 10:30
-```
-
-```
-$ blogwatcher-cli scan
-Scanning 1 blog(s)...
-
-  xkcd
-    Source: RSS | Found: 4 | New: 4
-
-Found 4 new article(s) total!
-```
-
-```
-$ blogwatcher-cli articles
-Unread articles (2):
-
-  [1] [new] Barrel - Part 13
-       Blog: xkcd
-       URL: https://xkcd.com/3095/
-       Published: 2026-04-02
-       Categories: Comics, Science
-
-  [2] [new] Volcano Fact
-       Blog: xkcd
-       URL: https://xkcd.com/3094/
-       Published: 2026-04-01
-       Categories: Comics
-```
-
-## Notes
-
-- Auto-discovers RSS/Atom feeds from blog homepages when no `--feed-url` is provided.
-- Falls back to HTML scraping if RSS fails and `--scrape-selector` is configured.
-- Categories from RSS/Atom feeds are stored and can be used to filter articles.
-- Import blogs in bulk from OPML files exported by Feedly, Inoreader, NewsBlur, etc.
-- Database stored at `~/.blogwatcher-cli/blogwatcher-cli.db` by default (override with `--db` or `BLOGWATCHER_DB`).
-- Use `blogwatcher-cli <command> --help` to discover all flags and options.