Docs

justin-napolitano/news-reader / README.md

News Reader

Synced 2026-10-23 · Updates are made in the source repository.

News Reader

A small local news reader for high-quality sources without ad-heavy article pages.

The app indexes configured RSS/Atom feeds, shows a clean feed, and extracts readable article text on demand. It keeps the original source URL visible and does not persist extracted article copies.

Direction

This repo is the first reader/client for the Open Intel Graph: a user-owned intake graph for sources, works, reading events, annotations, and project connections.

Start with Project Intent, then use the research system, bibliography, and exec plans to plan implementation slices.

Production operating notes live in News Reader Production Runbook.

Run

npm run dev

Open http://localhost:4175.

The reader is private by default. Login with username admin and set the passcode outside git:

NEWS_READER_ADMIN_PASSCODE=...
NEWS_READER_SESSION_SECRET=...

Set NEWS_READER_AUTH_REQUIRED=0 only for local unauthenticated development.

Deploy

This repo includes a Vercel serverless entrypoint in api/index.js and routes all traffic through vercel.json.

Target domain: news.selectproj.com.

Required Vercel environment variables:

  • NEWS_READER_ADMIN_PASSCODE
  • NEWS_READER_SESSION_SECRET
  • NEWS_READER_CRON_SECRET
  • LIFE_GRAPH_API_BASE_URL
  • LIFE_GRAPH_WRITE_TOKEN
  • NEWS_READER_ITEMS_SOURCE=life_graph

Recommended production values:

  • NEWS_READER_ADMIN_USER=admin
  • NEWS_READER_COOKIE_SECURE=1

VERCEL=1 also makes cookies secure automatically.

Deployment requirements are captured in ops/vercel/news-reader.manifest.json. Secret values stay in an untracked .env.vercel.production file or your shell environment.

Set VERCEL_TOKEN in your shell when pushing env vars or attaching the domain through the repo scripts.

Example .env.vercel.production:

NEWS_READER_ADMIN_PASSCODE=...
NEWS_READER_SESSION_SECRET=...
NEWS_READER_CRON_SECRET=...
LIFE_GRAPH_API_BASE_URL=...
LIFE_GRAPH_WRITE_TOKEN=...
NEWS_READER_ITEMS_SOURCE=life_graph
NEWS_READER_ADMIN_USER=admin
NEWS_READER_COOKIE_SECURE=1

Plan and push Vercel config from the shell:

npm run vercel:env:seed
npm run vercel:env:plan
npm run vercel:env:push
npm run vercel:domain:plan
npm run vercel:domain:add

The seed and push scripts print key names and targets only. They never print secret values.

Sources

Edit data/sources.json.

Each source needs:

  • id: stable machine id
  • name: display name
  • section: rough grouping
  • feedUrl: RSS or Atom feed
  • allowHosts: domains allowed for on-demand reader extraction

AP was not seeded because https://apnews.com/index.rss returned 401 during setup from this machine.

In production, source management should happen through /admin.html and Life Graph. Saving a source with an existing feed URL updates that existing source instead of creating a duplicate. Removing a source disables it so historical article state is retained, and saving it again restores the source.

Intel Graph

This repo now exposes read-only normalized graph objects:

  • GET /api/graph/sources
  • GET /api/graph/contracts
  • GET /api/graph/works
  • GET /api/life-graph/migrations
  • GET /api/life-graph/status
  • POST /api/life-graph/import/dry-run
  • POST /api/life-graph/import/remote-dry-run
  • POST /api/life-graph/import/apply
  • POST /api/items/refresh
  • GET /api/admin/refresh/status
  • GET /api/life-graph/intel/sources
  • GET /api/life-graph/intel/works
  • GET /api/life-graph/intel/reader/works
  • POST /api/life-graph/intel/reader/state
  • POST /api/life-graph/intel/retention/apply

Contracts live in contracts/. Fixtures live in test/fixtures/intel-graph/.

The Life Graph adapter is intentionally dry-run first. Raw intel is modeled in a proposed LifeDB intel_graph schema, while selected records can later be promoted into Life Graph life_object records and derived_from_source edges. See docs/schema/intel-graph-lifedb.md.

Proposed LifeDB migrations live in integrations/life-graph/migrations/. They are review artifacts for jnap-life-graph; copy or vendor them there only after reviewing the migration manifest.

After the Life Graph migration/API is available, this repo can call it directly. Configure secrets in .env, not in repo files:

LIFE_GRAPH_API_BASE_URL=http://127.0.0.1:8787
LIFE_GRAPH_WRITE_TOKEN=...
NEWS_READER_ITEMS_SOURCE=life_graph

The reader UI defaults to feed mode. Set NEWS_READER_ITEMS_SOURCE=life_graph to read article cards from jnap-life-graph with feed fallback for local development.

Use /review for mobile triage. The review deck reads the unread inbox, supports swipe-right save, swipe-left archive, paragraph-by-paragraph on-demand reading, keyboard controls, and one-step undo. It uses the same reader-state API as the standard list reader.

With the local reader server running:

npm run life-graph:status
npm run life-graph:dry-run
npm run life-graph:push-dry-run
npm run life-graph:apply
npm run life-graph:reader-works
npm run life-graph:retention
npm run life-graph:sources
npm run life-graph:works

When NEWS_READER_ITEMS_SOURCE=life_graph, the front page defaults to the unread inbox. Clicking an article marks it read, Save keeps it in the saved view, Dismiss hides it from the inbox, and Archived exposes hidden items for review. Retention is dry-run first through npm run life-graph:retention; Life Graph owns the durable policy and state tables.

Daily Import

The production app exposes a machine-only endpoint for scheduled feed ingestion:

GET /api/cron/news-import
Authorization: Bearer $NEWS_READER_CRON_SECRET

The endpoint fetches the configured RSS/Atom sources, applies the News Reader import to Life Graph, and returns a compact summary with local import ids and remote counts. It bypasses the browser login but requires NEWS_READER_CRON_SECRET.

GitHub Actions runs this endpoint every three hours from .github/workflows/daily-news-import.yml. Configure these repo settings:

  • GitHub Actions secret: NEWS_READER_CRON_SECRET
  • Optional GitHub Actions variable: NEWS_READER_BASE_URL, defaults to https://news.selectproj.com

The schedule is 17 */3 * * * UTC, roughly every three hours, and can also be run manually with workflow_dispatch.

Run contract validation with:

npm run contracts

Reader Rules

  • Feed index comes from RSS/Atom.
  • Article text is extracted only when you click a story.
  • Extracted text is cached in memory for a short local session.
  • Original source links stay visible.
  • This is a personal reader, not a republishing surface.

Checks

npm run smoke

Production read-only smoke test:

NEWS_READER_BASE_URL=https://news.selectproj.com \
NEWS_READER_ADMIN_USER=admin \
NEWS_READER_ADMIN_PASSCODE=... \
npm run smoke:production