Publume Core

Publume Core is a configuration-first personal information and publishing engine. It collects recent source material and linked article evidence, merges reports about the same event, extracts source-bounded facts and uncertainty, generates validated articles, commits them to a separate site repository, and can deliver them through optional notification channels.

The project is designed for scheduled GitHub Actions runs. It has no database, long-running server, or bundled site theme.

Project status: Publume Core is pre-1.0. Configuration and storage contracts may change before the first stable release.

How it works

RSS / Atom / JSON / HTML
            |
            v
normalize -> deduplicate -> recency and hard filters
            |
            v
 fetch selected article pages -> merge same-event reports
            |
            v
 evidence gate -> verified facts + uncertainty + source set
            |
            v
   multilingual generation -> source/runtime validation
            |
            v
       target site repository -> site deployment workflow
            |
            v
 Telegram / webhooks / ntfy / Matrix / email

A scheduled run can succeed without publishing anything. Candidates that are duplicate, stale, unsupported, low-value, unsafe, or below the configured score threshold are rejected before they reach the target repository.

“Evidence verification” has a strict boundary: Core asks the publication gate to extract supported facts, conflicts, and missing details from fetched reports. It then gives generation only that approved context and deterministically enforces the exact source set. Factual adherence still depends on the configured model and evaluation; Core does not independently prove a claim or replace human review.

Requirements

• Bun 1.3.14 or newer
• Git 2.39 or newer
• An OpenAI-compatible chat completions endpoint
• A writable target Git repository
• A compatible theme repository for first-time site creation

Deploy from GitHub

For a self-hosted deployment, start from the green Use this template button on Publume/core. Do not fork the repository or use the local-development commands below as the deployment entry point.

The shortest working path is:

1. create your own Core repository from this template;
2. create a separate, empty public repository for the website;
3. enable GitHub Actions as the website repository's Pages source;
4. add the required Core repository variables and secrets;
5. run Generate and publish once in initial mode and verify the Pages URL;
6. keep the template's daily GitHub schedule, or optionally deploy the Cloudflare Trigger Worker after the website is live.

Follow the GitHub manual deployment guide in English or 简体中文 for the exact settings, token permissions, success checks, and common failure fixes.

Local quick start

git clone https://github.com/Publume/core.git
cd core
bun install --frozen-lockfile
cp .env.example .env

Configure at least these values in .env:

AI_PROVIDER=openai-compatible
AI_API_KEY=your-api-key
AI_BASE_URL=https://your-provider.example/v1
AI_MODEL=your-model

TARGET_REPOSITORY=owner/site-repository
TARGET_REPO_TOKEN=your-fine-grained-token

SOURCE_URLS="https://source.example/feed.xml"
# Required only when SOURCE_URLS contains https://www.producthunt.com/feed
PRODUCTHUNT_API_TOKEN=your-product-hunt-developer-token
CONTENT_INSTRUCTIONS="Describe the audience, subject, and publication standard."
SITE_TYPE=general

Then verify the repository and create the target site with baseline content:

bun run check
bun run initial

Run the normal pipeline with:

bun run run

Never commit .env or any API token. The checked-in .env.example contains no working credentials.

GitHub Actions

The user-owned Scheduled generation workflow runs once per day at 00:00 UTC and calls the Core-managed Generate and publish workflow. Generate and publish also supports manual runs and repository_dispatch events of type publume-schedule.

Store credentials as repository secrets:

• AI_API_KEY
• TARGET_REPO_TOKEN
• PRODUCTHUNT_API_TOKEN when SOURCE_URLS contains the Product Hunt Feed
• DELIVERY_CONFIG when notification channels are enabled

For the first initial run, TARGET_REPO_TOKEN must be scoped to the target site repository with both Contents and Workflows read/write permission. See the manual deployment guide before creating it.

Store non-secret configuration as repository variables. See Configuration for the complete list.

For first-time setup, repository creation, and Pages configuration, follow the GitHub manual deployment guide in English or 简体中文.

The Worker in scheduler/ is optional. Its default Cron runs at 23:50 UTC on the previous UTC day, ten minutes before the daily GitHub schedule, and dispatches the same Core workflow. A successful Worker-triggered run makes the next GitHub scheduled run skip Core; without a successful Worker run, GitHub remains the fallback. Deploy the Worker only after the first website publication succeeds. GITHUB_TOKEN must be configured as a Cloudflare Worker secret, and GITHUB_REPOSITORY must be configured as a Worker environment variable.

Edit .github/workflows/schedule.yml to change the self-hosted GitHub Cron. Core upgrades preserve this user-owned file while updating the managed generation workflow and application code.

Themes and sites

Core does not contain Astro, layouts, styles, translations, or page components. On the first initial run it fetches THEME_REPOSITORY at THEME_REF, copies its shared site runtime, validates the selected THEME, and overlays that visual theme into an empty target repository. The overlay owns its visual tokens in theme.css; later runs only write article content and generated site identity and behavior configuration.

The theme and target marker contracts are documented in Architecture. Maintained themes belong in the separate Publume/themes repository.

Running the Upgrade Publume Core workflow synchronizes a requested Core release into a managed repository while preserving its state/ directory and user-owned .github/workflows/schedule.yml. Running Generate and publish in bootstrap mode replaces the selected theme while preserving generated articles. Both operations are designed for Publume Cloud but remain available to self-hosted users. A successful first initial run installs and builds the theme even when no candidate is publishable. Its summary contains the Website commit in targetCommitSha; published may be zero, and later scheduled runs can add validated articles.

Development

bun run typecheck
bun test
bun run acceptance

The acceptance test creates a minimal theme and temporary Git repositories at runtime, and uses local fixture sources plus a fake AI client. It never calls a real AI provider or pushes to GitHub.

Prompt changes have a separate live evaluation that uses the configured AI provider without collecting or publishing content. See Prompt evaluation for its dataset, thresholds, and evidence boundary.

To run the same acceptance flow against a local Publume Themes checkout:

PUBLUME_THEME_DIRECTORY=../themes bun run acceptance

To keep the generated, built Website for browser inspection, pass a new output directory and start its Astro preview:

PUBLUME_THEME_DIRECTORY=../themes bun run acceptance -- --output=/tmp/publume-site-preview
bun install --frozen-lockfile --cwd /tmp/publume-site-preview
bun run --cwd /tmp/publume-site-preview preview

See CONTRIBUTING.md before opening a pull request. Security issues must follow SECURITY.md, not the public issue tracker.

License

Publume Core is licensed under the Apache License 2.0.