Merge dev: fix review issues (stale weights, docs, config)

Author: Axect

QUICKSTART.md

@@ -18,19 +18,20 @@ uv run axp prefs add-category hep-ph --priority 2
 uv run axp prefs add-category cs.AI --priority 1
 uv run axp prefs add-category quant-ph
 
-# Add keywords you're interested in
-uv run axp prefs add-keyword "quantum" --weight 1.5
-uv run axp prefs add-keyword "machine learning" --weight 2.0
+# Add keywords you're interested in (1-5 stars)
+uv run axp prefs add-keyword "quantum" --weight 4
+uv run axp prefs add-keyword "machine learning" --weight 5
 
 # View your settings
 uv run axp prefs
 ```
 
 > **How priority and weight affect recommendations**
 >
-> - **Category priority** (default: 1) — Priorities are normalized relative to each other. If you set hep-ph=2 and cs.AI=1, hep-ph papers receive twice the category matching bonus. The category score contributes 20% of the total recommendation score.
-> - **Keyword weight** (default: 1.0) — Weights are applied directly as a multiplier. A keyword with weight 2.0 contributes twice as much as one with weight 1.0 when found in a paper. The keyword score contributes 10% of the total recommendation score.
-> - Categories with no explicit `--priority` default to 1; keywords with no `--weight` default to 1.0.
+> - **Category priority** (default: 1) — Priorities are normalized relative to each other. If you set hep-ph=2 and cs.AI=1, hep-ph papers receive twice the category matching bonus.
+> - **Keyword weight** (default: 3, range: 1-5 stars) — Higher stars mean stronger influence. A 5-star keyword contributes more than a 1-star keyword when found in a paper.
+> - **Recommendation weights** — Configurable in the TUI Prefs tab. Defaults: Content 60%, Category 20%, Keyword 15%, Recency 5%.
+> - Categories with no explicit `--priority` default to 1; keywords with no `--weight` default to 3.
 
 ### Configure AI Provider (Optional)
 
@@ -184,18 +185,19 @@ Launch the interactive terminal UI with `uv run axp tui`.
 2. **Search** — Search arXiv
 3. **Lists** — Manage reading lists
 4. **Notes** — Browse paper notes
-5. **Prefs** — Manage categories, keywords, and AI settings
+5. **Prefs** — Manage categories, keywords, authors, weights, and AI settings
 
 **Keyboard Shortcuts**:
-- `Enter` — Open paper detail modal
+- `Enter` — Open paper detail overlay
 - `l` — Like paper
 - `d` — Dislike paper
 - `s` — Generate AI summary
 - `t` — Translate paper
-- `n` — Add note
-- `a` — Add to reading list
-- `r` — Refresh current tab
-- `?` — Show all shortcuts
+- `r` — Generate AI review
+- `b` — Bookmark paper
+- `f` — Fetch papers (Daily tab)
+- `j` — Toggle jobs panel
+- `a` — Add item (Prefs tab: category/keyword/author)
 - `q` — Quit
 
 ## Helpful Defaults
@@ -217,10 +219,10 @@ uv run axp show       # → shows recently liked papers
 
 ## Recommendation Algorithm
 
-Papers are scored using a weighted combination:
-- **Content similarity** (50%): TF-IDF cosine similarity to your liked papers
+Papers are scored using a weighted combination (defaults, configurable in Prefs tab):
+- **Content similarity** (60%): TF-IDF cosine similarity to your liked papers
 - **Category matching** (20%): Priority of matched categories
-- **Keyword matching** (10%): Weighted keyword presence
+- **Keyword matching** (15%): Weighted keyword presence (1-5 stars)
 - **Recency** (5%): Bonus for papers published in the last 30 days
 
 The more papers you `like`, the better the recommendations become.

src/arxiv_explorer/cli/preferences.py

@@ -46,7 +46,7 @@ def remove_category(
 @app.command("add-keyword")
 def add_keyword(
     keyword: str = typer.Argument(..., help="Keyword"),
-    weight: float = typer.Option(1.0, "--weight", "-w", help="Weight"),
+    weight: int = typer.Option(3, "--weight", "-w", help="Importance (1-5 stars)"),
 ):
     """Add a keyword interest."""
     service = PreferenceService()

src/arxiv_explorer/core/config.py

@@ -19,12 +19,6 @@ class Config:
     default_fetch_days: int = 1
     default_result_limit: int = 20
 
-    # Recommendation weights
-    content_weight: float = 0.5
-    category_weight: float = 0.2
-    keyword_weight: float = 0.1
-    recency_weight: float = 0.05
-
     @classmethod
     def default(cls) -> "Config":
         """Load default configuration."""

tests/test_recommendation.py

@@ -37,7 +37,7 @@ def test_no_category_match_gives_zero_category_score(
         )
         results = engine.score_papers([paper], None, sample_categories, [])
         # Score should be very small (only recency if applicable, no category)
-        assert results[0].score < tmp_config.category_weight
+        assert results[0].score < 0.20  # default category weight (20%)
 
 
 class TestKeywordScoring: