Search & Discovery

AI Web Feeds uses two related search models inside the same product flow: source search for the catalog and post search for the generated article library.

The Search & Discovery experience lives across the primary reader route /reader and the explicit source catalog route /sources. It answers two different questions from one workspace:

Source search helps you find feeds in the curated catalog.
Post search helps you find recent articles in the generated article library.
Autocomplete draws from both so suggestions stay useful while you type.

Source Search

/reader is the default reader route.

/reader opens the article workspace
/sources opens the explicit source picker
/sources/[sourceId] exposes crawlable source metadata
/topics/[topicId] exposes crawlable topic collections
/articles/[articleId] exposes noindex article attribution pages when a corpus exists

Article browse and search

Article browse and article search are backed by data/articles.generated.json, which is exported from feed_entries in the runtime database.

That means the reader workspace can:

search titles, summaries, feed titles, authors, categories, and topics across the exported corpus
filter by feed, topics, source_type, and verified
page through results with cursor-based pagination
sort by latest, oldest, or source

The article list is served by GET /api/articles, while ranked article search uses GET /api/search?scope=articles.

Catalog search

Catalog search remains backed by the checked-in feed catalog.

Use catalog mode when you want to:

filter feeds by source type, topic, or verification state
pin one or more feed IDs into the article workspace
move from source discovery into the reader without leaving the canonical workspace

This keeps source discovery available even if the runtime corpus has not been generated yet.

Autocomplete

Autocomplete returns a shared suggestion set that can include:

feeds
articles
topics

That helps the main search box stay useful whether you are starting from a publication name or a subject area.

Refreshing the Current Results

Use Refresh latest when you want to check for new posts from the current source list. The generated article library stays the base dataset, and fresh posts are layered on top only when they are truly new.

Zero-Result Recovery

When no results match, the app offers direct recovery actions such as:

clearing the post filters
resetting the current filters
opening /sources to review the current source list

CLI and API

Catalog search is also available through the CLI and API routes:

# Optional backend for search analytics logging
BACKEND_URL=http://localhost:8000

Usage

Web Interface

Navigate to /reader:

Type a query in the workspace search bar
Keep or adjust the shared source-type, topic, verified, and pinned-feed filters
Press Enter to refresh the article list, or use autocomplete suggestions
Switch to /sources when you need to change the source list
Use Refresh latest when you want a non-destructive live overlay on top of the corpus

Keyboard Shortcuts:

Cmd/Ctrl+K: Focus search bar
Arrow keys: Navigate autocomplete suggestions
Enter: Execute search

CLI

# Catalog search
uv run ai-web-feeds search "transformer attention" --limit 20
uv run ai-web-feeds search autocomplete openai --limit 5

Relevant web routes:

// Corpus-backed article browse
const browse = await fetch("/api/articles?q=agents&sort=latest&limit=24");

// Source search
const response = await fetch("/api/search?q=transformer&scope=sources&limit=20");
const results = await response.json();

// Article search
const articleResults = await fetch("/api/search?q=neural%20networks&scope=articles&limit=20");

// Autocomplete
const suggestions = await fetch("/api/search/autocomplete?prefix=mach");

Performance

Autocomplete: Shared catalog/corpus suggestions with cacheable GET responses
Source Search: Reads checked-in data without depending on a backend runtime
Article Browse/Search: Reads the generated corpus artifact instead of running live feed scans on demand

Zero Results Handling

When no article or catalog results are found inside the primary reader workspace, the UI now offers direct recovery actions instead of leaving the user at a dead end.

reset to the full catalog when a feed slice is over-constrained
jump straight back into the article workspace when catalog filters get too narrow
clear article-specific filters while preserving the underlying source list
open catalog mode with the current source constraints so you can inspect or widen them

The UI still reinforces the broader guidance of:

returning to catalog mode for broader source discovery
fewer filters
a wider topic or source-type scope
rebuilding the generated corpus if the workspace reports that the artifact is unavailable

Success Criteria

✅ Reader /reader works without a required Python HTTP backend
✅ Article browse and article search run across the generated corpus
✅ Source results can jump directly into the article workspace inside the primary route model
✅ Autocomplete suggestions are built from the same catalog/corpus model used by the reader

Dashboard and Analytics - Understand the compact dashboard and backend analytics APIs
Reader - Browse and triage the corpus-backed timeline inside /reader
Recommendations - Backend recommendation API reference
Search architecture - Runtime and local search split