prdigest 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8788f06c317608d4ae85c2784408764af17e36148becd307a9332f853f7bb7eb
-  data.tar.gz: e975b567596a673fabf283ae5b81e1c85bc901f3f54c71b5275bd24c29f1c3f8
+  metadata.gz: 9ff60040fe7091056de1781ae7154e758145cf7216ec1b664adc661cd479c96f
+  data.tar.gz: aa87baccb18ac37b7398c83e5d312187e3d697fa8fa9e161c6f3b930cef73ae4
 SHA512:
-  metadata.gz: e20edb4683ef19cb47b498258536f1f5ef6b51331a69e41aa1730b5c65d7d72dc6418f260ea58bccffa47aaf564150dad24da53358f04bf85500cc19982f11c0
-  data.tar.gz: 4ff9015ad80f6624b7ba726bd3c616dff0890c9eec6ffd0315a3d840dee07c7123295d5c914f99d3cac420254c2167c7a93325dbbe85b843c42d454f3f34657d
+  metadata.gz: 2e7499399445ffa51a7acb8bd0f7066bf3f930108d56f070cafdfdc49e4a8b6727b6288b3a5e95cae3ed36f6e01c19fa90726522c6aeb731a45edf1c6a88718a
+  data.tar.gz: 7bc1c60e8518b9abebeb1beb6fdb08b12aafb39beb4056db7f96fc225b2344e9643f5d27108138a4eecb06d100db16f55c18dd075ffdc35152087b7f5ad58dc3

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.3.0 - 2026-07-27
+
+- Remove `prdigest run`, deterministic Telegram HTML, schedule/cursor state,
+  catch-up processing, the `prdigest-result` envelope, and the `serve` stub.
+- Keep `prdigest facts` for agents and `prdigest prose` for stdout or
+  checkpointed plain-text Telegram delivery.
+- Make `prdigest prose --deliver` the systemd and container default.
+
+## 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,155 +1,319 @@
-# PRDigest
+<div align="center">
 
-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.
+<h1>PRDigest</h1>
 
-## Requirements and installation
+<p><strong>One merged-PR facts contract. Prose for people and JSON for agents.</strong></p>
 
-- 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
+<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>
 
-For development:
+<p>
+  Give OpenClaw and other agents stable merged-PR facts, or generate concise<br>
+  prose through any 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 --> 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]
+```
+
+- **Stable facts for agents** — repository order, pull-request order, and JSON
+  shape are deterministic.
+- **AI stays explicit** — `facts` never 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
+
+| What you need | Command | Result | Side effects |
+|---|---|---|---|
+| Facts for OpenClaw or another agent | `prdigest facts` | `prdigest-facts` JSON on stdout | No Telegram, provider, or delivery state |
+| Provider-written text | `prdigest prose` | Plain text on stdout | Fresh run calls GitHub, then the provider; no Telegram or checkpoint |
+| Scheduled or one-off Telegram prose | `prdigest prose --deliver` | Checkpointed plain-text Telegram delivery | Fresh run calls GitHub and provider, persists, then sends; resume reuses the checkpoint |
+
+All modes accept `--date YYYY-MM-DD` and repeatable
+`--repo OWNER/NAME` overrides. Repository order is always preserved.
+
+## Quick start
+
+### 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
 ```
 
-To build and install the prepared gem without publishing it:
+Before running a delivery command from the source checkout, change the copied
+config to state paths writable by your user:
+
+```yaml
+state:
+  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=...       # 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 Telegram, delivery state, or prose provider
+bundle exec prdigest facts --config prdigest.yml
+
+# Provider-written text on stdout: no Telegram or delivery checkpoint
+bundle exec prdigest prose --config prdigest.yml
+```
+
+### 3. Deliver intentionally
+
+```sh
+# 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.3.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
+    - owner/api
+    - owner/web
+
+digest:
+  line_stats: true
+
 telegram:
   token_env: TELEGRAM_BOT_TOKEN
   chat_id_allowlist: [-1001234567890]
   chat_id: -1001234567890
-digest:
-  line_stats: true
-  send_empty: true
-  empty_message: "Merged PR digest — {date}\nTotal: 0 PRs"
+
 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
-prdigest run [--config PATH] [--date YYYY-MM-DD] [--dry-run] [--json] [--repo OWNER/NAME ...]
-prdigest serve
+- Repository order controls digest order.
+- `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`; `facts` ignores it.
+- Remote provider URLs require HTTPS. Plaintext HTTP is accepted only for exact
+  loopback hosts.
+
+</details>
+
+## Command reference
+
+```text
+prdigest facts [--config PATH] [--date YYYY-MM-DD] [--repo OWNER/NAME ...]
+prdigest prose [--config PATH] [--date YYYY-MM-DD] [--repo OWNER/NAME ...] [--deliver]
 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
+### `facts`
 
-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.
-
-State is secret-free JSON version 1:
+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
-{"version":1,"timezone":"Europe/London","last_digested_date":"2026-07-15"}
+{
+  "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
+    }
+  }
+}
 ```
 
-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.
+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
+plain-text chunks are 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 another provider.
+
+## Delivery guarantees
+
+PRDigest treats sending as a durable protocol, not a best-effort loop:
+
+1. Fetch facts and generate the complete prose digest.
+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.
+
+Once a prose 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>Date and checkpoint details</strong></summary>
+
+Each local day is converted to independent UTC midnight boundaries, including
+DST gaps and repeats. Both commands use yesterday in the configured timezone
+unless `--date YYYY-MM-DD` is supplied.
 
-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.
+Checkpoint directories are mode `0700`; files and locks are mode `0600`.
+A per-date lock prevents concurrent sends for the same repository scope and
+chat. While a completed checkpoint exists, repeating `prose --deliver` for that
+date is a no-op. Moving that checkpoint aside intentionally allows complete
+regeneration and redelivery.
 
-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.
+The supplied systemd timer invokes `prose --deliver` once each day. PRDigest
+does not maintain a catch-up cursor: explicitly run missed dates with `--date`.
 
-## systemd deployment
+</details>
 
-On Ubuntu, install Ruby, `tzdata`, the gem, and then:
+## 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
+```
+
+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.
+
+## Deployment
+
+<details open>
+<summary><strong>systemd on Ubuntu</strong></summary>
+
+Install Ruby, `tzdata`, and the gem, then:
 
 ```sh
 sudo useradd --system --home /nonexistent --shell /usr/sbin/nologin prdigest
@@ -158,69 +322,87 @@ 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.
+
+</details>
 
-## Container
+<details>
+<summary><strong>Container</strong></summary>
 
-The Alpine image includes `tzdata` and runs as the unprivileged `prdigest` user.
-Initialize mounted ownership with the image before normal use:
+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
+checkpoint backup, then restart. 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 | — |
+| `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` | Checkpoint state failure | Path, owner, mode, checkpoint JSON |
+| `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. Overlapping delivery
+for the same date is refused by the checkpoint lock; the systemd oneshot is the
+normal scheduler.
 
-## 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

data/SECURITY.md

@@ -12,10 +12,42 @@ Telegram bot whose `chat_id` is the only delivery target in the allowlist. Rotat
 either token immediately if it may have appeared in output, then inspect and
 restrict journal retention.
 
+Standalone prose uses the environment variable named by
+`prose.api_key_env`. Never place the provider key itself in YAML, shell history,
+arguments, checkpoints, fixtures, or logs. Remote provider URLs must use HTTPS;
+plaintext HTTP is accepted only for exact `localhost`, IPv4 `127.0.0.0/8`, or
+IPv6 `::1` loopback hosts. PRDigest rejects provider URLs with embedded
+credentials, query strings, or fragments and does not include provider response
+bodies in errors. Generated prose containing C0/C1 terminal controls is rejected
+before stdout, checkpoints, or Telegram; tabs and newlines remain allowed.
+
 Private pull-request titles and author names cross from GitHub into the configured
 Telegram chat. Treat that chat and its members as having access to repository
 metadata. PRDigest refuses non-allowlisted chat IDs before opening a connection.
 
+`prdigest facts` writes repository names, titles, authors, URLs, merge times, and
+optional statistics to stdout. The caller owns that output after the single JSON
+document is emitted; avoid terminal capture, shell tracing, and logs that are
+broader than the repository's audience.
+
+OpenClaw mode sends that facts document into the configured OpenClaw execution
+and model boundary so OpenClaw can write prose. Standalone `prdigest prose`
+sends the same complete document plus the configured model name to the
+OpenAI-compatible endpoint. Private repositories therefore require an OpenClaw
+deployment or provider whose data handling, retention, and access controls are
+acceptable to the operator. Provider access is never ambient: `prdigest facts`
+does not contact the standalone prose provider.
+
+Pull-request fields are untrusted input. The built-in provider prompt and the
+OpenClaw skill explicitly classify the facts JSON as data, never instructions,
+but operators should still restrict tools and authority available to any model
+processing private repository content. The OpenClaw skill must not make a second
+GitHub query, deliver messages, install software silently, or print credentials.
+
+Prose Telegram checkpoints contain generated text derived from repository facts.
+They use secret-free mode-`0600` files inside mode-`0700` directories. Protect,
+retain, and delete them as private repository metadata.
+
 ## Reporting
 
 Report vulnerabilities privately to the maintainer address in the gem metadata.
@@ -25,4 +57,6 @@ state files, or unredacted journal output.
 ## Supported release
 
 Security fixes target the latest published release. The build and test process
-does not tag or publish releases automatically.
+does not tag or publish releases automatically. The exact-tag release workflow
+uses a RubyGems trusted publisher and a short-lived GitHub OIDC credential; no
+long-lived RubyGems API key is stored in the repository or Actions secrets.