Paper 0.1.0

Paper 0.1.0 is the first stable release. It closes the 0.1 Stable milestone and
adds the iPad reader fixes below to alpha.4. This is a 0.1 release for single-user
installations. Keep backups before upgrading.

Changes since alpha.4

• iPad bottom tabs have more padding and at least 44px touch targets. The layout
  follows the visible viewport as browser controls change its height.
• Opaque headers and tabs keep text readable. Reader controls return without
  fading or sliding over articles.
• Article navigation no longer fades or slides the incoming document. Boundary
  gestures stop scrolling before switching articles, and cancelled gestures
  respect reduced-motion preferences.
• iOS and iPadOS home-screen apps keep header controls below the system's
  top-edge blur. A shorter header row limits the extra height. Settings and
  discussions use the same top inset.

See #62 and the
changelog.

What shipped across the alphas

Paper can run standalone, storing subscriptions, articles, search and reading
state locally. It collects feeds on a schedule and supports feed discovery,
flat folders and OPML import/export. FreshRSS remains an alternative backend.
Readable reader links support direct navigation, refresh and offline reading;
old links still work.

Security fixes add Host validation, framing protection, destination checks and
limits on outbound fetches. Optional AI runs in an isolated Codex worker over an
authenticated Unix socket, without Paper's data mount, environment file or network.
OpenCode support was removed. AI, Readwise Reader and Kirby remain optional.

Install

Follow the 0.1.0 quick start.
Start new installations in standalone mode. Runtime and AI images target Linux
amd64. The runtime archive and SHA-256 checksum provide a fallback when GHCR is
unavailable; the archive does not include the AI worker.

Paper has no built-in login. Keep its port on loopback or use an
authenticated HTTPS proxy.

Upgrade from alpha.4

Schema v12 is unchanged. Upgrading from 0.1.0-alpha.4 needs no database migration
or new configuration.

1. Stop Paper and every briefing command. For AI installs, stop paper-ai too.
   Back up the full data directory and private configuration. Back up AI login
   files and FreshRSS separately when used.

2. Preserve your Compose and proxy overrides, backend, account and saved secrets.
   Fetch and check out the release:

   git fetch origin tag v0.1.0
   git switch --detach v0.1.0

3. Without AI, pull and recreate Paper:

   sh scripts/pull-image.sh
   docker compose up -d --no-build paper

   With AI, pull and recreate both services, including your usual proxy overrides:

   docker compose -f compose.yaml -f compose.ai.yaml pull paper paper-ai
   docker compose -f compose.yaml -f compose.ai.yaml up -d --no-build --force-recreate paper paper-ai

4. Verify startup, articles, reading positions and saved state. Check AI
   availability if enabled. Do not rerun setup over the existing configuration.

For older alphas, follow the
earlier-alpha upgrade steps.
Those upgrades can require schema migrations and changes to AI and proxy setup.
Changing the backend setting does not transfer data between FreshRSS and standalone.
The offline FreshRSS migration tool is no longer included.

Limits

Clearer refresh controls and a visible feed-check schedule remain open in
#33. Refresh runs due feeds
only; it does not force every feed to fetch again.

Folders are flat. OPML transfers subscriptions, not article history or settings.
Offline browser copies are not server backups or a durable queue of FreshRSS
writes. Identity conflicts have no dedicated resolution UI. Broad searches and
very large article bodies still have a processing cost.

Entirely AI-coded. If this steals kittens, don't blame me.

Paper 0.1.0-alpha.4

Paper 0.1.0-alpha.4 is an early alpha. It adds readable reader links, fixes mobile
scroll jumps and feed recovery, and isolates AI in a separate worker container.
Existing AI and proxy installations need the upgrade steps below.

Start new installations as standalone. FreshRSS remains supported, but the
offline FreshRSS migration tool is no longer included. See the
changelog
for changes since alpha.3.

Reading and feed management

• Reader links use short paths such as /feed/12/the-verge/a/48213. Old links
  still work. New paths support direct navigation, refresh and offline reading.
• Mobile articles keep their position when controls hide. Saved reading progress
  adjusts while fonts load. Reader actions fit narrow panes, and story options
  have a separate keyboard-accessible button.
• Unread-only mode hides feeds and folders with nothing unread, even after a
  failed update. Feed management lists failing feeds under Needs attention.
• Feed recovery supports JSON Feed and bounded repairs for publisher XML errors.
  URL repair preserves subscriptions and reading history. Reused publisher IDs
  no longer overwrite distinct articles. Undated articles sort by first fetch,
  and failed collection passes retry with backoff.
• FreshRSS reads preserve saved article bodies, search limits upstream pages per
  request, and concurrent database writers wait instead of failing immediately.

Full-text reading, filters, keyboard shortcuts and offline article copies remain
available. AI, Readwise Reader and Kirby are optional.

Security and AI isolation

Paper checks the Host header to block DNS rebinding and prevents other sites
from framing it. Article, social avatar and X-thread fetches check destinations
and redirects and limit response sizes. Full-text extraction allows four active
requests; excess requests return a retry message. Malformed XML normalization
has bounded work. Docker images use Node 24.22.3, and the optional Caddy proxy
image is pinned by digest.

Codex runs in a separate paper-ai container over an authenticated Unix socket.
The worker has no Paper data mount or Paper environment file and shares no
network with Paper. It runs without root privileges, with a read-only root
filesystem. Batch runs disable the same tools as discussions, with the container
isolating Paper's files from tools the CLI cannot remove.

Two model runs execute at once, with up to 16 waiting requests. Busy requests
get a retry message. Logs contain request IDs and failure categories without
prompts or model output. Briefings share concurrent requests within a Paper
process, cancel work when no caller remains, and have a ten-minute deadline.
OpenCode support was removed. Codex is now the only supported AI runner.

Install or upgrade

Follow the alpha.4 quick start.
Runtime and AI images target Linux amd64. The runtime also has a downloadable
archive and SHA-256 checksum for the pull helper when GHCR is unavailable.
The archive does not include the AI worker. Source builds remain supported.

Paper has no built-in login. Keep its port on loopback or use an
authenticated HTTPS proxy.
Before upgrading:

1. Stop Paper and every briefing command. Back up the full data directory and
   private configuration. Back up AI login files and FreshRSS separately when
   used. Alpha.4 uses schema v12, adding link_numbers. Startup creates and
   validates paper.sqlite.before-link-numbers-v12 before migrating an existing
   database. An image rollback does not undo this migration. Restore the matching
   pre-upgrade database backup for a downgrade. Follow
   backup and restore.
2. For AI installs, run sh scripts/setup.sh --ai-worker-secret from the updated
   checkout to add PAPER_AI_WORKER_SECRET. Keep ai-auth/codex, match
   PAPER_UID:PAPER_GID to its non-root owner, and use the updated AI Compose
   override to pull and recreate both paper and paper-ai. Remove old
   Paper-side AI image overrides, auth mounts and local CLI settings. Follow
   every AI upgrade step.
   Without the worker, AI stays unavailable. Reading and saved AI results remain.
3. OpenCode-only installs must configure Codex and enable it in Settings.
   OPENCODE_* variables are ignored with a startup notice. Paper no longer
   mounts the old OpenCode login directory and does not delete it.
4. Preserve the original Host header in your proxy. Set PUBLIC_URL to the URL
   you use, including hostname and port. Mismatches return HTTP 421, and Paper
   does not trust X-Forwarded-Host. Loopback hosts remain allowed. See
   proxy configuration.
5. Set briefing automation timeouts to at least 660 seconds, including n8n HTTP
   requests, to allow the ten-minute generation deadline to finish.

Keep the backend and account that own your database. Changing configuration alone
cannot move FreshRSS data into standalone mode. Use a separate data directory for
a fresh standalone installation.

Limits

Folders are flat. OPML imports can partly succeed and report results per
subscription. OPML transfers subscriptions, not article history or settings.
Feed discovery and collection block private network destinations unless an
operator allows an exact trusted origin. Offline browser copies are not server
backups or a durable queue of FreshRSS writes. Identity conflicts still have no
dedicated resolution UI. Broad searches and very large article bodies still
have a processing cost.

Known alpha issues

These follow-ups remain open:

• #33: clearer refresh controls.
• #34: iPad bottom padding.
• #35: header blur report, unconfirmed.
• #36: article-transition flicker.

Validation status before publication

The release candidate passed 784 tests, type checks, a production build, all
three server smoke suites and the separate article-cleanup regression. The
collection fixture used 200,000 synthetic articles. All 50 browser layout tests
and six route tests passed in the Playwright container with Chromium and WebKit.
License notices are unchanged, and both dependency audits report no vulnerabilities.

Local runtime and AI image builds passed, along with disposable Docker
installation tests for standalone, FreshRSS, proxy authentication, settings and
restore. The real pinned Codex CLI passed the worker isolation regression
against a local scripted provider. It checked file and environment isolation,
blocked network access to Paper, socket permissions, restart recovery, and
briefing, collection and discussion requests. No real AI login or live provider
was used. These checks do not verify a user's provider login or model access.

GitHub checks must pass on the committed candidate before merge. Tagging and
artifact publication follow the reviewed merge; local validation does not mean
the release images or archive have been published.

Entirely AI-coded. If this steals kittens, don't blame me.

Paper 0.1.0-alpha.3

Paper 0.1.0-alpha.3 is an early alpha. Start with a fresh standalone installation.
FreshRSS snapshot migration is advanced and experimental; unknown publisher IDs
can produce historical duplicates and a large unread backlog on first collection.

Paper can now run as a standalone feed reader. New setup explicitly selects
PAPER_BACKEND=standalone, with subscriptions, articles, search and reading state
stored locally. No FreshRSS account or optional integration credentials are
needed. Existing installations that omit PAPER_BACKEND retain FreshRSS mode.
See the changelog
for changes since alpha.2.

Standalone reading and feed management

• Fetch RSS, Atom and RDF feeds automatically, with conditional requests,
  persistent schedules and retry backoff. Successful fetches default to a
  15-minute interval, subject to Retry-After. The scheduler checks for due work
  every second; Refresh runs due feeds only.
• Use the sidebar + menu to add a feed or create a standalone folder. Select
  the Edit feeds pencil for drag grips, selection checkboxes and row options.
  Changes save immediately; Done exits edit mode. Create, rename and order
  flat folders, rename or move feeds, and unsubscribe while retaining article
  history. FreshRSS operations follow its capabilities and retain upstream folder
  order; the optional helper lets Paper read that order.
• Discover feeds from a website or feed URL. Preview OPML imports, choose folder
  mappings and resolve conflicts before applying. Export subscriptions as OPML.
• Keep stable article and subscription IDs across renames, moves, repeated imports
  and restarts. Content refreshes preserve read/star state, reading positions and
  saved references. Standalone state changes and undo check revisions when
  supplied, so stale edits cannot silently undo newer work.

Feed refreshes and common-term searches now use indexed full-text row lookups
and metadata queries on large article collections. Slow local searches run in a
separate worker while reading and state updates continue. Search keeps its complete
result snapshots and relevance ordering. One search runs at a time, with up to
eight waiting requests; excess requests receive a retryable HTTP 503. Broad
searches still cost more as result counts grow.

Article cleanup replaces repeated regex scans with structural source-range
edits for enclosures, hero blocks, syndication footers and broken image links.
It retains the sanitizer and avoids the reproduced collection stalls. Synthetic
regressions cover those cases; arbitrary HTML sizes and nesting depths still
have a processing cost.

Missing or invalid publication dates no longer crash article rendering. Source
navigation ignores stale loads and reloads after browser page restoration. Pending
mark-read, undo and bulk-preview responses no longer replace a newer selection.
Next/previous navigation continues across feeds as well as folders, and source
loading supports browsers without the optional abort helpers. The viewport-jump
and transition-flicker reports below remain open.

Full-text reading, filters, keyboard shortcuts and offline article copies remain
available. AI, Readwise Reader and Kirby are optional. AI uses the separate AI
image and a CLI login; Kirby drafts need a compatible publishing plugin.

Install or upgrade

Follow the alpha.3 quick start.
The runtime and optional AI images target Linux amd64. The runtime image also
has a downloadable archive and SHA-256 checksum. The image-pull helper uses that
archive if GHCR is unavailable. Source-build instructions remain in the README.

Paper is an early single-user alpha with no built-in login. Keep its port on
loopback or use an authenticated HTTPS proxy.
Alpha.3 uses database schema 11. Before upgrading, stop Paper and every briefing
command and back up the entire data directory and private configuration. Protect
saved tokens, generated secrets and migration backups. Back up AI login files and FreshRSS separately when used.
An older image requires its matching pre-upgrade database backup; changing the
image alone does not undo schema changes. See backup and restore.

Experimental FreshRSS snapshot migration

Use the offline migration guide.
Changing configuration alone cannot transfer database ownership. This is an
advanced cutover with recovery responsibilities, not the normal alpha setup path.

• Complete a FreshRSS import and state reconciliation, stop every Paper writer,
  back up, then preview and apply the exact reviewed migration digest. Migration
  uses the last completed local snapshot. It does not contact FreshRSS, capture
  later remote edits or claim an atomic snapshot of the remote account.
• Existing article and subscription IDs, read/star state, reading positions,
  discussions, briefings and folder memberships stay intact. Publisher identity
  mappings require explicit reviewed evidence. Similar URLs or dates never prove
  that two articles are the same. With unknown publisher IDs, the first standalone
  collection can import historical copies as new unread articles and inflate the
  inbox substantially. Original read states remain intact, but overall unread
  counts can grow. Preview cannot predict every future duplicate. There is no
  general public cleanup tool for this backlog.
• Preview reports folder naming conflicts and unsafe feed endpoints for explicit
  rename or pause decisions. Interrupted migration blocks normal startup until
  recovery completes.
• Rollback needs its own preview digest and explicit loss acknowledgement. It
  saves later standalone work in a verified backup, then restores the original
  source snapshot and settings. Restore the original FreshRSS configuration
  before restarting. There is no reverse sync or merge of standalone edits into
  FreshRSS. Keep both sets of backups.

Limits

Folders are flat; nested OPML groups need reviewed flat-folder mappings. OPML
imports can partly succeed and report results per subscription. OPML transfers
subscriptions, not article history, reading state or private settings.

Feed discovery and collection reject private network destinations unless an
operator explicitly allows an exact trusted origin. Feeds that need arbitrary
credentials or bypasses are outside the default setup. Offline browser copies
are device-local reading copies, not a server backup or a durable queue of
FreshRSS writes. Article identity conflict resolution still has no dedicated UI.

Known alpha issues

These follow-ups remain open:

• #32: readable URLs.
• #33: clearer refresh controls.
• #34: iPad bottom padding.
• #35: header blur report, unconfirmed.
• #36: article-transition flicker.
• #37: viewport jump when marking read and scrolling.

Validation status before publication

The release candidate passed 623 tests, type checking, a production build,
all three server smoke checks and the separate article-cleanup collection
regression. Runtime and AI image builds and disposable installations passed,
including FreshRSS compatibility, standalone startup, migration and rollback,
proxy authentication, settings persistence and restore. License notices are
unchanged; both dependency audits and the public-source secret scan passed.
AI CLI startup checks ran without network access and do not verify provider
login, model access or live model calls.

GitHub checks must pass on the committed candidate before merge. Tagging and
artifact publication follow the reviewed merge; local validation does not mean
the release images or archive have been published.

Entirely AI-coded. If this steals kittens, don't blame me.

Paper 0.1.0-alpha.2

Paper is a self-hosted reader for an existing FreshRSS account. This early alpha
includes full-text articles, local search, reading positions, filters, keyboard
shortcuts, and offline article copies.

This release adds optional AI, Readwise Reader, and Kirby controls in
Settings > Reading & connections, with setup instructions and token storage
and removal for Readwise and Kirby. AI uses the separate AI image and a CLI
login. Readwise saves articles. Kirby drafts require a compatible publishing
plugin on your site.

The sync diagnostic now compares entries in FreshRSS arrival order, independently
of publication dates and your reading order. This fixes false mismatches for
articles that arrive late. Reader sorting is unchanged.

Follow the quick start.
The published images support Linux amd64. The standard reader image also has a
downloadable archive and SHA-256 checksum; the pull-image helper uses that
archive if the registry is unavailable.

Paper is for one user and has no built-in login. Keep it local or use an
authenticated HTTPS proxy. Back up your data directory and configuration before
upgrading, and keep FreshRSS backed up separately.

Validation covers automated tests, builds, dependency and secret checks, and
disposable FreshRSS installations with both image variants. It includes settings
persistence, token removal, proxy authentication, and backup restoration. AI CLI
startup is checked without making live model calls.

Entirely AI-coded. If this steals kittens, don't blame me.

Paper 0.1.0-alpha.1

The first public Paper alpha is a single-user reader for an existing FreshRSS
account. It includes local search, reading positions, full-text extraction,
filters, and offline article copies. AI, Readwise, Kirby, and RSSHub connections
are optional and disabled until configured.

Use the README's setup instructions. The default reader image is Linux amd64
and binds to loopback in Compose. Protect remote access with an authenticated
HTTPS proxy. There is no built-in login or account isolation.

This release includes a versioned Docker image archive and its SHA-256 checksum.
The pull-image helper tries the registry first and can load the public archive
after checksum verification. The optional AI image can also be built from source.

Validation covers unit/component tests, type checks, production builds,
dependency audits, secret scans, a synthetic protocol smoke test, and a real
disposable FreshRSS 1.30.4 installation with proxy authentication and restoration.
AI CLI startup is checked; no live provider account or billable model request
is used in validation. This alpha has not had an independent security audit.

Paper is entirely AI-coded. Code provenance is not fully verified. The project
uses MIT where those rights can be granted and preserves third-party licenses.
See the provenance record and third-party notices. If this steals kittens,
don't blame me.