Smart feed matching

The matcher tries, in order:

1. raw feed_id prefix on what you typed,

2. order-id prefix when the input is purely numeric,

3. case-insensitive substring against the feed title or URL.

The completion menu shows entries as N — <Feed title>. Accepting one injects only the order-id N into the line — the dispatcher resolves it back to the canonical feed_id at run time. So

feed bbc<TAB>

becomes

feed 4

once you accept the BBC News entry. Entry_ids still match the same way against entry titles and are injected verbatim, scoped to whichever feed is in token 2.

Layout

Surface, Dim, and Faint tiers all share the same Title / Source / Summary layout — title on its own line, source on the next line in a recessed style, then the wrapped summary. Surface scales the title through the big preset and clips it to fit the river column, appending an ellipsis at the last word boundary that fits (the Surface title is single-line by design — long titles read in full once you press Enter). Dim drops the scaling; Faint runs the title and summary through a braille mask whose hardness rises with age. Beyond is the only one-liner.

[▶] Title
    Source
    Summary line one, wrapped to fit the column,
    capped at three lines with an ellipsis if longer.

The leftmost two cells carry the marker:

Age is conveyed by the title's color, not by an explicit time column: title color fades continuously by visibility — fresh items land on p.fg8 bold; old items ease into p.fg3. The summary sits one tier behind the title (p.fg4 → p.fg2) so the hierarchy reads at a glance. Beyond entries carry an explicit [YYYY-MM-DD] date stamp since their visibility is too low for the gradient to be informative.

Tiers and the bend

Each entry is assigned a tier from its visibility. Tiers map to render treatments:

The river is sorted by visibility descending (with effective_pub_ts as the tiebreaker), so tier transitions are monotone: Surface → Dim → Faint → bend → Beyond. The bend is a row of ~ in the gutter color, emitted once between the last river tier and the archive.

The Faint band has a soft entry: the last two Dim items above it pull their color toward the mask anchor (no braille noise yet), then mask hardness ramps from 5 at the top of Faint to 55 at the bottom. The mask anchor also lerps from p.fg2 (warmer) to p.fg1 (colder) across the band — even within the masked region, depth reads as a gradient instead of a flat block.

To keep the river short, the band is capped at 3 Faint entries. Anything that would have been the 4th Faint entry or beyond renders in Beyond format instead and lives below the bend.

Age, visibility, half-life, and retention

pub_ts = the feed-provided publish/update timestamp, or ingest time when missing
effective_pub_ts = pub_ts normally
effective_pub_ts = max(pub_ts, pin.last_surface_ts) when pinned

default_half_life = 86400 seconds

inferred_half_life = mean(post_intervals) * meta.half_life_multiplier
                    = mean(post_intervals) * 5.0 by default
                    clamped to [1h, 90d]

half-life <feed> <DUR>   => set half_life_seconds and freeze it
half-life <feed> auto    => re-enable inference

visibility = 0.5 ^ ((now - effective_pub_ts) / half_life_seconds)

purge_horizon = max(feed.half_life_seconds) * meta.purge_age_multiplier
              = max(feed.half_life_seconds) * 20 by default

Per-source diversity

After the visibility sort, a soft per-feed cap reorders the view: at most 3 entries from any one feed appear within any sliding window of 10 consecutive positions. Excess entries from a saturated feed are deferred and re-emitted once their feed drops back under the cap, so a high-volume feed (Hacker News, Lobsters) can't crowd the surface tier with a single source. Visibility ordering within a feed is preserved — we only reorder across feeds. Pinned entries bypass the cap so a pin burst always surfaces together.

Per-feed river_cap

cap <feed_id> <N> sets a hard ceiling on how many of a feed's entries can occupy slots above the bend (Surface + Dim + Faint). Set this for high-volume feeds when the diversity cap alone leaves too many of their entries visible — for example, cap hacker-news 5 keeps at most 5 HN entries in the visible river regardless of how many fresh ones the feed has. cap <feed_id> none removes the cap.

When a capped feed has more above-bend candidates than its cap, Lewis picks the survivors via visibility-weighted random sampling (A-Res with weight = visibility): fresher entries are more likely to survive, but every candidate has a nonzero chance, so a different subset rotates in on each light refresh (r in the river view). Pinned entries bypass the cap. The Beyond tier and the per-feed / search views are not affected — the cap only governs the visible river.

Streams

The river groups every feed together by default. With many subscriptions of mixed cadence — daily news, weekly newsletters, hourly aggregators — fast feeds drown out slow ones in the visible band. Streams carve the river into three speed classes:

Streams are computed automatically as adaptive terciles over the current subscription's half-life distribution — fast is whatever "fast" means in your set. The partition is recomputed on entry to the view and on every R (full refresh, half-lifes can drift after ingest). Fewer than 3 feeds disables streams (Tab flashes a reminder, the river falls back to all feeds).

The river opens on the fast stream by default. Press Tab to cycle through the streams:

fast → medium → slow → fast

Press a to drop the filter and show all feeds; press Tab again to drop back into the fast stream. The active stream name is shown on the left of the status line; "all feeds" is implied when the prefix is absent. Light refresh (r), pin (p), save (s), drown (d), and selection moves all preserve the active stream.

Pressing R while a stream is active only fetches the feeds in that stream — switch to "all feeds" with a first if you want a full sweep. Light r is store-only and never fetches, so its scope is purely the current view regardless.

Pinned and saved entries

Pinning sets last_surface_ts = pub_ts and auto-saves the entry. The timeline sorted set is re-scored to the pin's effective publish time, so the entry rejoins the river at the top. While pinned, an entry's "sort floor" is 0.4 — even if its raw visibility decays, it never sinks below the Dim tier visually.

A pinned entry resurfaces every resurface_seconds (default 7 days, overridable per-pin via --resurface). The bump fires on entry to the mode and once per flow open.

Saving without pinning preserves the entry against eviction but does not change its position in the river. Pin implies save; unpin does not clear saved (call unsave separately).

Drowned entries

drown is the mirror of pin: instead of bumping an entry to the top, it deletes the body. The summary, feed_content, and any cached fetched_content are dropped, the FT index entry is removed, any active pin is cleared, and saved is set to false. What stays is metadata — title, link, comments link, author, dates, tags — enough to remember the entry existed. The metaphor: you can't revive a dead entry, but you can still do an autopsy.

Drowned entries are absent from the river, the per-feed feed <fid> listing, and search. They show up only in drowned and via tab-complete on surface. surface restores visibility but does not restore the body — opening the entry afterwards falls back to the article reader stub that points at the original link.

Drowning does not preserve the entry against purge. Drowned entries are removed from the active river timeline immediately, but unsaved drowned entries still remain eligible for purge by age. If you want to keep something forever, save it explicitly.

River key bindings

The cursor anchors roughly one-third down the viewport — j and k advance or retreat which entry holds that position. The river itself is scrolled and re-painted around the anchor; selection follows. Near the start of the river the selection rides at row 1, and near the end it sinks past the anchor toward the bottom of the viewport (standard scroll-off in both directions).

Opening in a browser uses the registered desktop handler for https/http (the same mechanism xdg-open consults). If no handler is registered, the status line flashes "no browser handler registered".

Animations

Several transitions in the river view animate rather than snap:

• Scroll — j/k/J/K/g/G slide the viewport one or more lines per frame until the new selected entry rests at the anchor row. During motion every viewport row outside the selected entry's band is masked with braille noise, with hardness ramping from soft adjacent to the selection to hard at the viewport edges (warm anchor above, cold below). The selected entry itself stays crisp, so the eye locks onto the focal entry while the rest of the river blurs. Single-line steps are not animated; page and edge jumps are capped to ~300 ms total regardless of distance.

• Drown — pressing d keeps the just-drowned entry on screen as a "ghost" that descends one row per frame, dissolving into braille noise and bleeding toward the cold mask anchor as it sinks. The river behind it is already the post-drown view, so the entry visibly leaves the stream.

• Open — pressing Enter keeps the selected entry crisp while every other viewport row dissolves into spaces, then the article reader takes over. The fetch for the article body runs concurrently with the dissolve so the pager opens with cached content.

• Light refresh — pressing r dissolves every row outside the selected entry's band into spaces (~180 ms), the river is re-read from the store and re-laid-out against the current time, then the new river materialises by reversing the dissolve (~180 ms). No network activity; the visible reorder is purely visibility decay.

• Stream cycle — pressing Tab reuses the light-refresh dissolve: the river fades out around the current selection, the filter advances to the next stream, the records are re-read with the new filter applied, and the (likely different) subset materialises in place.

• Full refresh — pressing R plays a cold mask wave that descends row-by-row over the river before alt-screen tears down for the network fetch (~300 ms). Per-feed status lines print at the prompt during the fetch. When the river returns, a clean front rises from the bottom of the viewport, peeling the mask away over ~420 ms, revealing the post-fetch river.

A keystroke during any animation cuts it short and dispatches immediately. Set LEWIS_REDUCED_MOTION=1 (or true/yes/on) to disable all animations and restore instant transitions; the variable is read fresh on each keystroke, so it can be flipped without restarting the mode.

Half-life inference

Per feed, Lewis tracks the last 10 inter-post intervals. The inferred half-life is:

half_life_seconds = mean(post_intervals) * meta.half_life_multiplier   (default 5.0)
                    clamped to [1h, 90d]

Intervals come from both:

• gaps between multiple newly seen entries in the same refresh, and

• gaps across refreshes via the feed's remembered latest seen pub_ts

So a feed that produces one post per refresh still accumulates interval history over time.

Recomputed on every successful refresh that yields ≥ 1 new entry with a valid publish timestamp.

half-life <feed_id> <DUR> overrides the value and freezes it (half_life_inferred = false); half-life <feed_id> auto reverts to inferred. Manual overrides are clamped to the same [1h, 90d] envelope as inference, so a fat-finger value (30s, 200d) lands at the nearest bound rather than a degenerate visibility regime.

Eviction

purge removes entries older than the current purge horizon, where:

purge_horizon = max over feeds of (half_life * meta.purge_age_multiplier)   (default 20.0)

Pinned entries and entries with saved = true are exempt. Unsaved drowned entries are also eligible for purge. The operation also clears FT index entries.

A daily feed with half_life ≈ 24h keeps about 20 days of history; a weekly feed with half_life ≈ 7d keeps about 4.5 months.

Keyspaces

Defaults written into meta on first open:

Feed and entry IDs

feed_id = sha256(canonical_url)[:16] (hex). Trailing slashes and scheme are normalised before hashing, so https://x.com/rss and https://x.com/rss/ produce the same id.

entry_id is taken from the feed's <guid> / <id> when present (sanitised), otherwise from sha256(link || title || pub_ts)[:16]. Re-ingesting the same entry_id updates mutable fields (title, summary, content) but never pub_ts — a publisher editing a post does not bring it back to the top of the river.

CALM-backed semantic layer

Lewis already reserves a commands slot for embed [<feed_id>|all] and similar <feed_id> <entry_id>. Both will be wired to a CALM embedding model loaded by lilush:

• embed walks entries and writes a vector per entry into a separate MNEME embeddings keyspace, keyed identically to the FT index (feed_id:entry_id). The vector source is title || "\n" || summary. The keyspace is gated on the lilush build path (lilu does not load CALM), so the vector layer is a no-op there.

• similar looks up the entry's vector and returns top-k cosine neighbours, presented through the archive view.

The expected payoff is duplicate clustering (the same story from two outlets ends up adjacent in vector space) and a better "more like this" navigation than BM25 over short summaries can offer.

Misc

• Dynamic river flow (lewisd)

• Cross-feed deduplication (the same article from two sources). The CALM embedding layer is the most likely vehicle.

• Per-category half-life defaults (currently per-feed only).