prdigest 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8788f06c317608d4ae85c2784408764af17e36148becd307a9332f853f7bb7eb
-  data.tar.gz: e975b567596a673fabf283ae5b81e1c85bc901f3f54c71b5275bd24c29f1c3f8
+  metadata.gz: 409ae44cab5ad005c5dcb413632295fdd3aae2e8d6383852b71863f8fc484d15
+  data.tar.gz: 7ae70339af9e94123d83795362bfde4c07ee57d94bf447123fe4ce305f9117b4
 SHA512:
-  metadata.gz: e20edb4683ef19cb47b498258536f1f5ef6b51331a69e41aa1730b5c65d7d72dc6418f260ea58bccffa47aaf564150dad24da53358f04bf85500cc19982f11c0
-  data.tar.gz: 4ff9015ad80f6624b7ba726bd3c616dff0890c9eec6ffd0315a3d840dee07c7123295d5c914f99d3cac420254c2167c7a93325dbbe85b843c42d454f3f34657d
+  metadata.gz: f5c7c0e265e13c87e2a625c3ee8fd10cde644b99297277b0dd5fd1f2f4a980ea0d7d81f67a63021b9741af8811b8903af47595c9713b507dd36fb749118e4489
+  data.tar.gz: 4c787a605900e7f93722a72929708cf5032e35d1aff08a2134d41430d6e17b58f578ef20d965141391c87943eefbe3e99781a99cfcf72f08e0b35257c90d1d50

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.2.0 - 2026-07-26
+
+- Add a deterministic `prdigest facts` JSON contract over the canonical
+  collection engine without scheduling, Telegram, or provider side effects.
+- Add optional OpenAI-compatible prose for stdout or explicit checkpointed
+  Telegram delivery, with provider failures kept visible.
+- Restrict plaintext provider URLs to strict loopback hosts and reject generated
+  terminal control characters before output or delivery.
+- Add a repository-owned, ClawHub-ready OpenClaw skill that writes prose only
+  from validated PRDigest facts.
+- Prove the facts command from an isolated installed gem without provider or
+  network access beyond the stubbed GitHub boundary.
+
 ## 0.1.1 - 2026-07-25
 
 - Accept Octokit `Time` objects as well as ISO-8601 strings for pull-request

data/README.md

@@ -1,125 +1,311 @@
-# PRDigest
+<div align="center">
+
+<h1>PRDigest</h1>
+
+<p><strong>One source of truth for merged pull requests. Three ways to present it.</strong></p>
+
+<p>
+  <a href="https://github.com/ivankuznetsov/prdigest/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/ivankuznetsov/prdigest/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://rubygems.org/gems/prdigest"><img alt="Gem version" src="https://img.shields.io/gem/v/prdigest.svg"></a>
+  <a href="https://www.ruby-lang.org/"><img alt="Ruby 3.2+" src="https://img.shields.io/badge/Ruby-3.2%2B-CC342D?logo=ruby&amp;logoColor=white"></a>
+  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+</p>
+
+<p>
+  Collect merged PRs once, then deliver a deterministic Telegram digest, emit<br>
+  stable JSON for an agent, or generate optional prose through an
+  OpenAI-compatible Chat Completions endpoint.
+</p>
+
+<p>
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#choose-a-mode">Choose a mode</a> ·
+  <a href="#configuration">Configuration</a> ·
+  <a href="#deployment">Deploy</a> ·
+  <a href="#openclaw">OpenClaw</a>
+</p>
+
+</div>
+
+---
+
+## Why PRDigest?
+
+PRDigest keeps collection separate from presentation. Every mode starts from
+the same ordered, immutable facts, so adding an agent or prose model never
+changes what was fetched from GitHub.
+
+```mermaid
+flowchart LR
+    GH[GitHub repositories] --> C[Canonical collector]
+    C --> RUN["prdigest run<br/>deterministic Telegram"]
+    C --> FACTS["prdigest facts<br/>versioned JSON"]
+    C --> PROSE["prdigest prose<br/>provider-written text"]
+    FACTS --> OC[OpenClaw or another client]
+    PROSE --> OUT[stdout or explicit Telegram delivery]
+```
+
+- **Deterministic by default** — repository order, pull-request order, and JSON
+  shape are stable.
+- **AI stays optional** — neither `run` nor `facts` configures or contacts a
+  prose provider.
+- **Safe to resume** — delivery checkpoints prevent already accepted chunks
+  from being sent twice.
+- **Secrets stay out of config** — YAML names environment variables; it never
+  contains token values.
+
+## Choose a mode
 
-PRDigest is a deterministic Ruby oneshot that sends a daily digest of merged
-GitHub pull requests to one allowlisted Telegram chat. It is designed for a
-single operator on a small VPS: repositories are explicit, secrets stay in the
-environment, and a hardened systemd timer owns scheduling.
+| What you need | Command | Result | Side effects |
+|---|---|---|---|
+| Reliable scheduled digest | `prdigest run` | Deterministic Telegram HTML | Reads/writes schedule and delivery state |
+| Facts for OpenClaw or another client | `prdigest facts` | `prdigest-facts` JSON on stdout | No schedule state, Telegram, or AI provider |
+| Provider-written text | `prdigest prose` | Plain text on stdout | Fresh run calls GitHub, then the provider; no Telegram or checkpoint |
+| Provider-written Telegram digest | `prdigest prose --deliver` | Checkpointed Telegram delivery | Fresh run calls GitHub and provider, persists, then sends; resume uses the checkpoint without GitHub/provider generation |
 
-## Requirements and installation
+All modes accept `--date YYYY-MM-DD` and repeatable
+`--repo OWNER/NAME` overrides. Repository order is always preserved.
 
-- Ruby 3.2–3.4 and `tzdata`
-- a fine-grained GitHub token with read-only access to the listed repositories
-- a dedicated Telegram bot and one destination chat ID
+## Quick start
 
-For development:
+### 1. Install from source
+
+Ruby 3.2 or newer and `tzdata` are required. CI covers Ruby 3.2–3.4.
 
 ```sh
+git clone https://github.com/ivankuznetsov/prdigest.git
+cd prdigest
 bundle install
-bundle exec prdigest version
-GITHUB_TOKEN=... bundle exec prdigest run --config configs/config.example.yml --dry-run
+cp configs/config.example.yml prdigest.yml
+```
+
+Before running a delivery command from the source checkout, change the copied
+config to state paths writable by your user:
+
+```yaml
+state:
+  path: tmp/prdigest/state.json
+  delivery_path: tmp/prdigest/deliveries
+```
+
+Keep the example's `/var/lib/prdigest` paths for the packaged systemd
+deployment, which creates that directory for the `prdigest` service user.
+
+Edit `prdigest.yml`, then export the narrowly scoped credentials needed by the
+mode you plan to run:
+
+```sh
+export GITHUB_TOKEN=github_pat_...
+export TELEGRAM_BOT_TOKEN=...       # run or prose --deliver only
+export OPENROUTER_API_KEY=...       # prose only; use your configured env name
+```
+
+Use a fine-grained GitHub token with read-only access to the configured
+repositories. Delivery modes should use a dedicated Telegram bot and one
+allowlisted destination chat.
+
+### 2. Try the read-only paths
+
+```sh
+# Stable JSON: no scheduler state, Telegram, or prose provider
+bundle exec prdigest facts --config prdigest.yml
+
+# Deterministic Telegram preview: fetches GitHub but does not send or save state
+bundle exec prdigest run --config prdigest.yml --dry-run
+
+# Provider-written text on stdout: no Telegram or delivery checkpoint
+bundle exec prdigest prose --config prdigest.yml
 ```
 
-To build and install the prepared gem without publishing it:
+### 3. Deliver intentionally
+
+```sh
+# Scheduled deterministic delivery
+bundle exec prdigest run --config prdigest.yml
+
+# Provider-written delivery, checkpointed before the first Telegram request
+bundle exec prdigest prose --config prdigest.yml --deliver
+```
+
+To build and install the current checkout as a gem without publishing it:
 
 ```sh
 gem build prdigest.gemspec
-gem install prdigest-0.1.1.gem
+gem install prdigest-0.2.0.gem
 prdigest version
 ```
 
-## Configuration and secrets
+The [published RubyGems version](https://rubygems.org/gems/prdigest) may trail
+the current `main` branch.
+
+### Publishing for maintainers
+
+RubyGems publication uses GitHub OIDC rather than a stored API key. Configure
+the `prdigest` gem's RubyGems trusted publisher with repository owner
+`ivankuznetsov`, repository `prdigest`, workflow `release.yml`, and environment
+`release`.
+
+Pushing a new exact `vX.Y.Z` tag publishes it automatically. To publish an
+existing prepared tag such as `v0.1.1`, run the **Release gem** workflow
+manually and supply that tag. The workflow checks that the immutable tag and
+package version agree, runs the unit and clean-install smoke suites, builds and
+verifies the exact gem, then exchanges GitHub's OIDC identity for a short-lived
+RubyGems credential immediately before `gem push`.
+
+## Configuration
 
-Configuration lookup is strict: an explicit `--config PATH` wins, then
-`PRDIGEST_CONFIG`, then an existing `/etc/prdigest/config.yml`. PRDigest refuses
-to run when none exists. See `configs/config.example.yml` for every setting.
+Lookup is strict: `--config PATH`, then `PRDIGEST_CONFIG`, then an existing
+`/etc/prdigest/config.yml`. PRDigest refuses to run when no configuration is
+found.
 
 ```yaml
 timezone: Europe/London
-schedule:
-  max_catchup_days: 7
+
 github:
   token_env: GITHUB_TOKEN
   repos:
-    - owner/repo-one
-    - owner/repo-two
-telegram:
-  token_env: TELEGRAM_BOT_TOKEN
-  chat_id_allowlist: [-1001234567890]
-  chat_id: -1001234567890
+    - owner/api
+    - owner/web
+
+schedule:
+  max_catchup_days: 7
+
 digest:
   line_stats: true
   send_empty: true
   empty_message: "Merged PR digest — {date}\nTotal: 0 PRs"
+
+telegram:
+  token_env: TELEGRAM_BOT_TOKEN
+  chat_id_allowlist: [-1001234567890]
+  chat_id: -1001234567890
+
 state:
   path: /var/lib/prdigest/state.json
   delivery_path: /var/lib/prdigest/deliveries
+
+prose:
+  provider: openai_compatible
+  base_url: https://openrouter.ai/api/v1
+  model: provider/model
+  api_key_env: OPENROUTER_API_KEY
 ```
 
-Repository order controls digest order. `max_catchup_days` must be `1..30`.
-`chat_id` must appear in the non-empty allowlist; extra allowlisted IDs are
-accepted for schema compatibility but v0.1.x sends only to `chat_id`. Token
-values belong in environment variables, never YAML.
+See [`configs/config.example.yml`](configs/config.example.yml) for the complete
+annotated configuration.
 
-## Commands and results
+<details>
+<summary><strong>Configuration rules</strong></summary>
 
-```sh
+- Repository order controls digest order.
+- `max_catchup_days` must be between `1` and `30`.
+- `chat_id` must appear in the non-empty allowlist. Extra IDs are accepted for
+  schema compatibility, but delivery sends only to `chat_id`.
+- Token values belong in environment variables, never YAML.
+- The prose block is validated only for `prdigest prose`; it does not ambiently
+  enable provider access for deterministic commands.
+- Remote provider URLs require HTTPS. Plaintext HTTP is accepted only for exact
+  loopback hosts.
+
+</details>
+
+## Command reference
+
+```text
 prdigest run [--config PATH] [--date YYYY-MM-DD] [--dry-run] [--json] [--repo OWNER/NAME ...]
+prdigest facts [--config PATH] [--date YYYY-MM-DD] [--repo OWNER/NAME ...]
+prdigest prose [--config PATH] [--date YYYY-MM-DD] [--repo OWNER/NAME ...] [--deliver]
 prdigest serve
 prdigest version
 ```
 
-An ordinary `run` reads state, processes owed dates oldest-first, and writes
-state after each settled day. `--date` replays exactly that local date and never
-reads or writes state. `--dry-run` previews the explicit date or yesterday,
-requires GitHub access, and constructs neither state nor Telegram delivery.
-`serve` remains a compatibility stub; use the supplied timer.
-Repeatable `--repo` values replace the configured repository list for that run.
-They use the same strict `owner/name` validation and deterministic order as the
-configuration, which lets callers such as Hive supply their registered projects
-without owning a second digest implementation.
-
-`--json` emits a versioned `prdigest-result` document with `status`, `mode`, `requested_days`,
-`settled_days`, `skipped_days`, `failed_date`, `remaining_days`, nullable
-`error`, dry-run `chunks`, and nullable structured `delivery` progress.
-`delivery` reports `accepted_chunks`, `total_chunks`, `status`, and, on failure,
-`failed_chunk`. Modes are `scheduled` and
-`explicit_date_replay`; statuses are `success`, `dry_run`, `failure`, and
-`partial_failure`.
-
-| Exit | Meaning |
-|---:|---|
-| 0 | completed or dry-run |
-| 1 | unexpected or render failure |
-| 2 | CLI/configuration refusal |
-| 3 | GitHub failure |
-| 4 | Telegram failure |
-| 5 | state failure |
-| 6 | failure after earlier durable progress |
-
-## Delivery and state semantics
+### `run`
+
+An ordinary run processes owed dates oldest-first and advances state after each
+settled day. `--date` replays exactly one local date without reading or writing
+the schedule cursor. `--dry-run` previews an explicit date or yesterday and
+constructs neither state nor Telegram delivery.
+
+`--json` emits a versioned `prdigest-result` document with requested, settled,
+skipped, failed, and remaining dates plus delivery progress. `serve` is a
+compatibility stub; use the supplied systemd timer for scheduling.
+
+### `facts`
+
+Fetches one explicit date or yesterday and prints exactly one JSON document. It
+never reads or writes scheduling state, constructs Telegram delivery, or
+contacts the prose provider.
+
+A complete successful empty digest looks like:
+
+```json
+{
+  "schema": "prdigest-facts",
+  "schema_version": 1,
+  "status": "success",
+  "error": null,
+  "digest": {
+    "date": "2026-07-25",
+    "timezone": "Europe/London",
+    "line_stats": true,
+    "repository_order": ["owner/api", "owner/web"],
+    "repositories": [
+      {"name": "owner/api", "pull_requests": []},
+      {"name": "owner/web", "pull_requests": []}
+    ],
+    "totals": {
+      "pull_requests": 0,
+      "additions": 0,
+      "deletions": 0,
+      "commits": 0
+    }
+  }
+}
+```
+
+The full digest includes ordered repositories and pull requests, authors, URLs,
+UTC merge times, nullable line and commit statistics, and aggregate totals.
+Disabled statistics remain `null`, not zero. There is no generation timestamp,
+so identical accepted GitHub input produces identical JSON.
+
+### `prose`
+
+Sends the same facts document as untrusted data to
+`<prose.base_url>/chat/completions`. The provider is instructed to present those
+facts without adding to or changing them.
+
+Without `--deliver`, prose is printed to stdout. With `--deliver`, the final
+escaped and chunked payload is stored under `state.delivery_path/prose` before
+the first Telegram request. Provider output containing terminal control
+characters is rejected before it can reach stdout, a checkpoint, or Telegram.
+
+There is no silent fallback to deterministic prose or another provider.
+
+## Delivery guarantees
+
+PRDigest treats sending as a durable protocol, not a best-effort loop:
+
+1. Fetch and render the complete day.
+2. Persist the exact final chunk list.
+3. Mark a chunk in flight before sending.
+4. Advance only after Telegram definitely accepts it.
+5. Resume at the next unsent chunk after a definite failure.
+
+A definite Telegram 429/5xx response receives at most three attempts. Transport
+failures are ambiguous because Telegram may have accepted the request before
+the connection failed; PRDigest parks them instead of risking a duplicate.
+
+Prose delivery uses its own checkpoint namespace. Once a payload exists, retry
+loads those exact chunks before checking GitHub or provider credentials, so a
+resume never regenerates different prose. A failure before the payload becomes
+durable can incur another provider request on retry.
+
+<details>
+<summary><strong>Scheduling, replay, and state details</strong></summary>
 
 Each local day is converted to independent UTC midnight boundaries, including
-DST gaps and repeats. GitHub results are completely fetched and rendered before
-the first Telegram message. A day is settled only after every chunk succeeds,
-an enabled empty message succeeds, or an empty message is intentionally
-suppressed.
-
-Before sending, PRDigest stores the complete rendered chunk list in
-`state.delivery_path`. It marks one chunk in flight before each request and
-advances `next_chunk` only after Telegram definitely accepts it. A definite
-429/5xx rejection receives at most three attempts; a later invocation resumes
-the original rendered payload at the next unsent chunk. If the date cursor write
-fails after complete delivery, the retry observes the completed delivery
-checkpoint and sends nothing before repairing the cursor.
-
-Telegram 400/invalid-response failures are permanent. Transport failures are
-ambiguous because Telegram might have accepted the request before the
-connection failed. Both cases remain parked and never replay automatically.
-Inspect the checkpoint and Telegram chat, reconcile the uncertain chunk, then
-move the checkpoint aside only when an intentional operator replay is safe.
-Changing the chat or repository scope for an existing date also fails closed.
-Explicit `--date` uses this same safety ledger, so a completed date is a no-op
-unless its checkpoint is deliberately archived first.
+DST gaps and repeats. A day settles only after every chunk succeeds, an enabled
+empty message succeeds, or an empty message is intentionally suppressed.
 
 State is secret-free JSON version 1:
 
@@ -127,29 +313,56 @@ State is secret-free JSON version 1:
 {"version":1,"timezone":"Europe/London","last_digested_date":"2026-07-15"}
 ```
 
-It may include a `last_skip` audit with `start_date`, `end_date`, and
-`notice_pending`. Writes use an atomic mode-`0600` replacement and directory
-fsync. Delivery directories are mode `0700`; delivery files and locks are mode
-`0600`, and a per-date lock prevents concurrent sends for the same checkpoint.
-Missing state means first run and requests yesterday only. Malformed,
-future, unsupported, unreadable, or timezone-mismatched state fails closed with
-exit 5.
+Writes use atomic mode-`0600` replacement and directory fsync. Delivery
+directories are mode `0700`; files and locks are mode `0600`. A per-date lock
+prevents concurrent sends for the same checkpoint.
+
+Missing state means first run and requests yesterday only. Malformed, future,
+unsupported, unreadable, or timezone-mismatched state fails closed.
+
+When backlog exceeds the configured cap, PRDigest durably skips the oldest
+prefix and processes only the newest window. For a timezone migration, stop the
+timer, preserve and move aside the old state, change timezone, explicitly
+replay any required dates, then restart the timer.
+
+GitHub does not guarantee search-index freshness. Keep the host timezone aligned
+with the digest timezone and use `--date YYYY-MM-DD` for a delayed merge found
+by a later audit. Explicit replay uses the same delivery ledger: while a
+completed checkpoint for that date exists, delivery is a no-op and newly
+rendered content is ignored. Intentionally archiving the checkpoint makes the
+next replay regenerate and send the complete date, not only the delayed pull
+request.
+
+</details>
+
+## OpenClaw
+
+The repository includes a ClawHub-ready skill at
+[`openclaw/skills/prdigest/SKILL.md`](openclaw/skills/prdigest/SKILL.md). It:
+
+- invokes only `prdigest facts`;
+- validates schema version 1 and the success envelope;
+- treats pull-request fields as untrusted data, never instructions;
+- makes no second GitHub request; and
+- never invokes delivery or configures a prose provider.
+
+The skill is source-ready, **not claimed as published**. After a separately
+authorized ClawHub release, the expected command is:
+
+```sh
+clawhub install @ivankuznetsov/prdigest
+```
 
-When backlog exceeds the cap, PRDigest durably skips the oldest prefix and
-processes only the newest window. That loss is intentional and reported. For a
-timezone migration, stop the timer, preserve the old state for audit, move it
-aside, change the configured timezone, use explicit replay for any required
-dates, then restart the timer. Never silently edit a corrupt checkpoint; inspect
-and repair ownership/JSON or restore a known-good copy first.
+ClawHub installation and Ruby CLI installation are separate trust boundaries.
+See [`openclaw/README.md`](openclaw/README.md) for local use and the
+release-gated publication checklist.
 
-GitHub does not publish a search-index freshness guarantee. Keep the host
-timezone equal to the configured digest timezone; the supplied 09:05 timer then
-leaves about nine hours after local midnight. If a later audit finds a delayed
-merge, use `--date YYYY-MM-DD` to replay it.
+## Deployment
 
-## systemd deployment
+<details open>
+<summary><strong>systemd on Ubuntu</strong></summary>
 
-On Ubuntu, install Ruby, `tzdata`, the gem, and then:
+Install Ruby, `tzdata`, and the gem, then:
 
 ```sh
 sudo useradd --system --home /nonexistent --shell /usr/sbin/nologin prdigest
@@ -158,69 +371,88 @@ sudo install -o root -g prdigest -m 0640 configs/config.example.yml /etc/prdiges
 sudo install -o root -g root -m 0600 .env.example /etc/prdigest/.env
 sudo install -o root -g root -m 0644 scripts/systemd/prdigest.service /etc/systemd/system/
 sudo install -o root -g root -m 0644 scripts/systemd/prdigest.timer /etc/systemd/system/
+sudoedit /etc/prdigest/config.yml
+sudoedit /etc/prdigest/.env
 sudo systemctl daemon-reload
 sudo systemctl start prdigest.service
 sudo systemctl enable --now prdigest.timer
 ```
 
-Edit the installed config and environment file before starting. systemd creates
-`/var/lib/prdigest` as `prdigest:prdigest` mode `0700`; state files are `0600`.
-Inspect with `systemctl status prdigest.service`, `systemctl list-timers
-prdigest.timer`, and `journalctl -u prdigest.service`. Test a missed-day catch-up
-by stopping the timer for a day, then starting the service. Journal output can
-contain repository/date context, so restrict journal group membership and
-retention.
+systemd creates `/var/lib/prdigest` as `prdigest:prdigest` mode `0700`.
 
-Rollback by stopping the timer, installing the prior gem/image, restoring the
-matching config and a known-good state backup, and restarting. Replay omitted
-dates explicitly; do not move a checkpoint forward by hand.
+```sh
+systemctl status prdigest.service
+systemctl list-timers prdigest.timer
+journalctl -u prdigest.service
+```
+
+Journal output can contain repository and date context, so restrict journal
+group membership and retention.
 
-## Container
+</details>
 
-The Alpine image includes `tzdata` and runs as the unprivileged `prdigest` user.
-Initialize mounted ownership with the image before normal use:
+<details>
+<summary><strong>Container</strong></summary>
+
+The Alpine image includes `tzdata` and runs as the unprivileged `prdigest`
+user. Initialize mounted ownership once before normal use:
 
 ```sh
-docker build -t prdigest:0.1.1 .
+docker build -t prdigest:local .
 docker volume create prdigest-state
-docker run --rm --user root --entrypoint sh -v prdigest-state:/var/lib/prdigest prdigest:0.1.1 \
+docker run --rm --user root --entrypoint sh \
+  -v prdigest-state:/var/lib/prdigest \
+  prdigest:local \
   -c 'chown -R prdigest:prdigest /var/lib/prdigest && chmod 0700 /var/lib/prdigest'
+
 docker run --rm --env-file /etc/prdigest/.env \
   -v /etc/prdigest/config.yml:/etc/prdigest/config.yml:ro \
-  -v prdigest-state:/var/lib/prdigest prdigest:0.1.1
+  -v prdigest-state:/var/lib/prdigest \
+  prdigest:local
 ```
 
-## Verification and troubleshooting
+</details>
+
+### Rollback
 
-`bundle exec rake test` is fully offline. Release preparation also supplies
-`test/smoke/gem_install.sh`, `test/smoke/docker.sh`, and
-`test/smoke/systemd.sh`. Live GitHub boundary and Telegram allowlist smokes are
-manual gates: retain timestamps and pass/fail only, never credentials, response
-bodies, message text, or private titles.
+Stop the timer, install the prior gem or image, restore its matching config and
+a known-good state backup, then restart. Replay omitted dates explicitly; never
+move a checkpoint forward by hand.
 
-- Exit 2: check config discovery, YAML, timezone, cap, chat allowlist, and env.
-- Exit 3: check repository access, rate/search limits, and replay later.
-- Exit 4: inspect `error.kind` and `delivery`. Retry ordinary `telegram` failures;
-  reconcile `telegram_ambiguous`, `telegram_permanent`, and
-  `delivery_checkpoint_permanent` before moving any checkpoint.
-- Exit 5: check `/var/lib/prdigest`, mode/owner, JSON version, date, and timezone.
-- Exit 6: earlier dates or a skipped prefix are durable; inspect the result before retry.
+## Exit codes and troubleshooting
 
-Concurrent scheduled runs remain unsupported because date-cursor scheduling is
-single-owner. Delivery itself takes a nonblocking per-date lock, so a competing
-sender fails instead of duplicating the same payload. The systemd oneshot is the
-normal run coordination mechanism.
+| Exit | Meaning | First check |
+|---:|---|---|
+| `0` | Completed or dry-run | — |
+| `1` | Unexpected or render failure | Logs and input shape |
+| `2` | CLI/configuration refusal | Config path, YAML, timezone, allowlist, env |
+| `3` | GitHub failure | Token scope, repository access, rate/search limits |
+| `4` | Telegram failure | `error.kind` and delivery checkpoint |
+| `5` | State failure | Path, owner, mode, JSON version/date/timezone |
+| `6` | Failure after durable progress | Settled/skipped dates before retry |
+| `7` | Provider failure or ambiguous outcome | Endpoint, model, key env, retry cost |
 
-See [SECURITY.md](SECURITY.md) for token scope, rotation, and private-data flow.
+Reconcile `telegram_ambiguous`, `telegram_permanent`, and
+`delivery_checkpoint_permanent` before moving a checkpoint. Concurrent
+scheduled runs are unsupported; the systemd oneshot is the normal coordinator.
 
-## Non-goals
+See [`SECURITY.md`](SECURITY.md) for token scope, rotation, and private-data
+flow.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+test/smoke/gem_install.sh
+test/smoke/docker.sh
+test/smoke/systemd.sh
+```
 
-v0.1.x has no built-in Hive configuration discovery, LLM content, web UI,
-interactive bot commands,
-multi-chat routing, organization discovery, non-GitHub forge support, or
-long-running scheduler. The build and test process never tags or publishes
-automatically.
+The test suite is fully offline. Live GitHub and Telegram smokes are manual
+release gates; retain only timestamps and pass/fail status, never credentials,
+response bodies, generated prose, or private titles.
 
 ## License
 
-MIT
+[MIT](LICENSE) © 2026 Ivan Kuznetsov