News Reader
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_PASSCODENEWS_READER_SESSION_SECRETNEWS_READER_CRON_SECRETLIFE_GRAPH_API_BASE_URLLIFE_GRAPH_WRITE_TOKENNEWS_READER_ITEMS_SOURCE=life_graph
Recommended production values:
NEWS_READER_ADMIN_USER=adminNEWS_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 idname: display namesection: rough groupingfeedUrl: RSS or Atom feedallowHosts: 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/sourcesGET /api/graph/contractsGET /api/graph/worksGET /api/life-graph/migrationsGET /api/life-graph/statusPOST /api/life-graph/import/dry-runPOST /api/life-graph/import/remote-dry-runPOST /api/life-graph/import/applyPOST /api/items/refreshGET /api/admin/refresh/statusGET /api/life-graph/intel/sourcesGET /api/life-graph/intel/worksGET /api/life-graph/intel/reader/worksPOST /api/life-graph/intel/reader/statePOST /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 tohttps://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