stash/PROPOSAL.md

Proposal: stash — self-hosted read-later with one-click capture

Status: proposed, not built. Self-contained — written so a fresh agent with no prior conversation context can pick this up and implement it without anything explained first. No repo exists yet; this file is the seed of one.

Motivation

Read-later tools (Pocket, Instapaper, and their many clones) all share the same shape as every other cloud convenience this household of projects has been replacing: a third party ends up holding a full copy of everything you've ever wanted to read, indefinitely, for a feature that's really just "save this page, let me read it later, let me search it eventually."

The actual want: click a button in the browser, the current page's article content gets pulled out and stored on infrastructure already run (alongside wisp, flit, keep), with a plain reading-list view and full text search over what's been captured.

A read-later tool with no one-click capture is just a bookmarks file with extra steps — so this is explicitly a two-piece project: a browser extension that does the sending, and a small server that does the storing. Neither piece is useful alone.

Architecture

Single-process server + SQLite, the same pattern already validated by galr (a photo gallery proving SQLite can carry an entire app's storage and query needs without a separate database service). No queue, no multi-service split — one process, one file on disk.

Data model

One table, articles:

column	type	notes
id	integer PK
url	text, unique	dedup key — see "Open questions"
title	text
content_html	text	cleaned article body, for the reader view
content_text	text	plain-text extract, indexed via FTS5 for search
author	text, nullable	best-effort, from extraction
published_at	text, nullable	best-effort, from extraction
captured_at	text	when the extension sent it
read_at	text, nullable	null = unread
tags	text	comma-separated or JSON array, keep simple

Full-text search via SQLite's FTS5 virtual table over content_text + title — no external search service, matches the "one process" bet.

Server endpoints

• POST /api/capture — body: { url, title, content_html, content_text, author?, published_at? }. Auth via a bearer token (see auth below). Upserts on url (see dedup, below).
• GET /api/articles?unread=true&q=<search> — list/search, most recent capture first.
• GET /api/articles/:id — full record, for the reader view.
• PATCH /api/articles/:id — { read_at } (mark read/unread), { tags }.
• DELETE /api/articles/:id
• A minimal server-rendered reader view (e.g. /read/:id) that serves content_html in a plain readable template — the point of capturing cleanly is a nicer reading experience than the original page, not just an archive.

Browser extension (Manifest V3)

• Toolbar icon + context-menu entry: "Send to stash"
• On click: injects a content script that runs Readability.js-style extraction (Mozilla's @mozilla/readability is the standard library for this — strips nav, ads, comments, keeps article body/title/author/date) against the current DOM
• If extraction confidence is low (Readability returns null or a very short result — common on heavily JS-rendered pages), fall back to capturing the page's raw rendered HTML rather than failing outright. Worse capture beats no capture for a personal tool.
• POSTs the extracted { url, title, content_html, content_text, author, published_at } to POST /api/capture
• Toolbar badge or toast confirms success/failure so a silent failure doesn't look like a successful capture

Auth

No login UI in the extension — that's overkill for a single-user tool. Instead: a settings page (extension's options page) with one field, a token pasted in once. The server generates that token via a CLI command or a one-time setup endpoint, the same "generate once, paste once" shape keep's identity registration already uses. Stored in chrome.storage.local, sent as Authorization: Bearer <token> on every capture.

What this deliberately isn't

• Not multi-user, no accounts, no sync protocol — one server, one reader (you), one writer (the extension on your own browser profiles). If two browsers both have the extension, they both hit the same server; there's no per-device state to reconcile.
• Not a visual/screenshot archive — text and article structure only (à la archive.org's Wayback Machine, which this is not trying to be). Keeps storage small and keeps full-text search meaningful — searching rendered screenshots isn't a thing.
• Not published to the Chrome Web Store or Firefox Add-ons — sideloaded/unpacked only (chrome://extensions → "Load unpacked", or Firefox's about:debugging temporary add-on). Store review, a developer account, and update-approval friction are all overhead for a tool with exactly one user. Tradeoff: Firefox's temporary add-ons don't survive a browser restart, so Chrome/Chromium (persistent unpacked extensions) is the more convenient target if only picking one browser to support first.

Open questions

• Dedup on re-capture — a url unique constraint plus upsert is the simplest behavior (re-sending the same URL just refreshes the stored copy). The alternative — versioning every capture — adds real complexity for a benefit ("see how this article changed over time") that's unlikely to matter for a personal reading list. Recommend upsert-on-url as the default; revisit only if it turns out to matter in practice.
• JS-heavy / paywalled sites — capture happens against whatever the DOM looks like at click-time, in the browser, as the logged-in user already sees it. This sidesteps needing server-side headless rendering entirely (no Puppeteer on the server, no cookie-jar management) — the extension captures exactly what's already rendered in front of the user. The limitation: if the page is still loading content asynchronously when "Send to stash" is clicked, that content won't be in the DOM yet. Not worth engineering around for a first cut; a "capture is incomplete, try again once the page fully loads" is an acceptable rough edge.
• Where does this live relative to keep — once keep is rolled out further (see goonk/FUTURE.md's "Roll out keep to the rest of the stack"), stash's server should probably pull its own bearer-token secret from keep rather than a hand-copied .env, the same way any new project should from here on. Not a blocker for a first version, since keep's rollout is itself still in progress.