feat(collections): curated reading tracks that seed the recommender

Cold start asks a new user to pick arXiv categories, but cs.LG is ~302k papers
-- far too coarse to retrieve against, and the resulting Tier 0 feed was a
citation sort. A collection is a much sharper signal: following one replays its
anchors through the ordinary save path, which puts the user straight past the
>=5-save threshold into Tier 1 multi-interest clustering and skips the weakest
part of the pipeline entirely.

Semantic Scholar's Research Feeds work exactly this way -- the feed is seeded
from a curated Library folder, with a documented minimum of "5 relevant papers
... and 3 non-relevant". Every track here carries at least 6 anchors, so one
click clears that budget.

Eight tracks, 66 anchors, each with a curator note: LLM inference, RAG,
agents, fine-tuning/alignment, diffusion, embeddings, scaling, evaluation.
All 66 verified present in the production vector store before writing a line of
UI -- an anchor with metadata but no embedding would render perfectly and
silently fail to seed anything.

Curated content lives in data/collections/*.json, NOT the database: DB_PATH is
/tmp, HF withdrew persistent storage, and anything hand-authored into SQLite
evaporates on rebuild. Keeping anchors in git also makes a curation edit
reviewable in a diff. Who follows what is user data and goes in
collection_follows, replicated by turso_sync.

JSON rather than YAML deliberately -- pyyaml is only present as a transitive
dependency of transformers, so a YAML loader would import in production and
fail in CI, where the test job installs the app deps minus the ML stack.

Three deliberate design decisions:

- The detail page keeps curated anchors and medoid-matched recent papers in
separately headed sections. Merging them would quietly pass off vector
search as editorial judgement.
- Unfollow does not unsave or rewind the profile. An EWMA is a lossy running
average with no exact inverse, so "undoing" a follow would leave a
permanent smudge while claiming to restore the previous state.
- follow() counts saves and profile updates separately and logs when they
diverge. A save without a resolvable vector is a library entry that teaches
the recommender nothing; that used to pass silently, which is how a
partially configured vector store looks like a working feature.

Reuses paper_card.html so save/pass and all Phase 4.5/6.5 instrumentation keep
working unchanged; seeded rows carry candidate_source=collection:<slug> and
policy_id=collection_seed, so the seeding path is separable in analysis.

The template-selector guard caught the follow button using an interpolated #id
selector -- the same class of bug as 6fca272. Uses hx-target="closest
.follow-wrap" instead, which needs no id at all.

283 tests pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

app/collections_svc.py

@@ -0,0 +1,158 @@
+"""
+Curated reading collections.
+
+Curated content lives in the REPO (data/collections/*.json), not the database.
+DB_PATH is /tmp on an ephemeral filesystem and Hugging Face has withdrawn
+persistent storage, so anything hand-authored into SQLite evaporates on the
+next rebuild. Keeping the anchors in git also makes an edit reviewable in a
+diff, which is what curation actually needs.
+
+Who follows what IS user data and lives in db.collection_follows, replicated
+by turso_sync like everything else.
+
+JSON rather than YAML deliberately: pyyaml is only present as a transitive
+dependency of transformers, so a YAML loader would import fine in production
+and fail in CI, where the test job installs the app dependencies minus the ML
+stack. Nothing here should need a dependency the tests do not have.
+"""
+from __future__ import annotations
+
+import json
+import os
+from functools import lru_cache
+
+import numpy as np
+
+COLLECTIONS_DIR = os.getenv(
+    "COLLECTIONS_DIR",
+    os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+                 "data", "collections"),
+)
+
+# How many medoid-matched recent papers to show under the curated anchors.
+EXTEND_LIMIT = int(os.getenv("COLLECTION_EXTEND_LIMIT", "12"))
+
+
+@lru_cache(maxsize=1)
+def load_all() -> list[dict]:
+    """Every collection, ordered by title. Cached; call cache_clear() in tests.
+
+    A malformed file is skipped rather than fatal -- one bad edit should not
+    take down the index page for the other seven.
+    """
+    out: list[dict] = []
+    if not os.path.isdir(COLLECTIONS_DIR):
+        print(f"[collections] no directory at {COLLECTIONS_DIR}")
+        return out
+
+    for name in sorted(os.listdir(COLLECTIONS_DIR)):
+        if not name.endswith(".json"):
+            continue
+        path = os.path.join(COLLECTIONS_DIR, name)
+        try:
+            with open(path, encoding="utf-8") as fh:
+                data = json.load(fh)
+            slug = str(data["slug"]).strip()
+            anchors = [
+                {"id": str(a["id"]).strip(), "note": str(a.get("note", "")).strip()}
+                for a in data["anchors"] if a.get("id")
+            ]
+            if not slug or not anchors:
+                raise ValueError("slug and at least one anchor are required")
+            out.append({
+                "slug": slug,
+                "title": str(data.get("title") or slug),
+                "blurb": str(data.get("blurb", "")),
+                "anchors": anchors,
+                "count": len(anchors),
+            })
+        except Exception as e:
+            print(f"[collections] skipping {name}: {type(e).__name__}: {e}")
+
+    out.sort(key=lambda c: c["title"])
+    return out
+
+
+def get(slug: str) -> dict | None:
+    slug = (slug or "").strip()
+    return next((c for c in load_all() if c["slug"] == slug), None)
+
+
+def anchor_ids(slug: str) -> list[str]:
+    c = get(slug)
+    return [a["id"] for a in c["anchors"]] if c else []
+
+
+def all_anchor_ids() -> set[str]:
+    return {a["id"] for c in load_all() for a in c["anchors"]}
+
+
+async def medoid(slug: str) -> np.ndarray | None:
+    """The centre of a collection, as the medoid of its anchor vectors.
+
+    Medoid rather than centroid, for the same reason clustering.py uses one:
+    it is an actual paper in the set, so the "recent work in this area" list is
+    anchored to something real rather than to a point in space that may sit
+    between two unrelated sub-topics.
+
+    Returns None when too few anchors resolve to vectors -- callers then simply
+    omit the extension section rather than showing something arbitrary.
+    """
+    from app import qdrant_svc
+    from app.recommend.clustering import _find_medoid
+
+    ids = anchor_ids(slug)
+    if not ids:
+        return None
+    try:
+        vectors = await qdrant_svc.get_paper_vectors(ids)
+    except Exception as e:
+        print(f"[collections] vector fetch failed for {slug}: {e}")
+        return None
+
+    found = [vectors[i] for i in ids if i in vectors]
+    if len(found) < 2:
+        print(f"[collections] {slug}: only {len(found)} anchor vectors -- no medoid")
+        return None
+
+    arr = np.asarray(found, dtype=np.float32)
+    # L2-normalise before averaging, matching clustering.py: cosine geometry is
+    # what the rest of the pipeline assumes.
+    norms = np.linalg.norm(arr, axis=1, keepdims=True)
+    norms[norms == 0] = 1.0
+    arr = arr / norms
+    centroid = arr.mean(axis=0)
+    return arr[_find_medoid(arr, centroid)]
+
+
+async def extend(slug: str, limit: int = EXTEND_LIMIT,
+                 exclude: set[str] | None = None) -> list[str]:
+    """Recent papers near the collection medoid, excluding the anchors.
+
+    This is what keeps a curated list from going stale without the curator
+    touching it: the anchors are the editorial judgement, and the vector index
+    supplies whatever has appeared since.
+    """
+    from app import qdrant_svc
+
+    vec = await medoid(slug)
+    if vec is None:
+        return []
+
+    skip = set(exclude or set()) | set(anchor_ids(slug))
+    try:
+        hits = await qdrant_svc.search_by_vector(
+            vec.tolist(), limit=limit + len(skip),
+        )
+    except Exception as e:
+        print(f"[collections] extend failed for {slug}: {e}")
+        return []
+
+    out: list[str] = []
+    for h in hits:
+        aid = h.get("arxiv_id") if isinstance(h, dict) else getattr(h, "arxiv_id", None)
+        if aid and aid not in skip and aid not in out:
+            out.append(aid)
+        if len(out) >= limit:
+            break
+    return out

app/db.py

@@ -133,6 +133,17 @@ CREATE TABLE IF NOT EXISTS feed_impressions (
 );
 CREATE INDEX IF NOT EXISTS idx_impr_user_time
     ON feed_impressions(user_id, shown_at DESC);
+
+-- Which curated collections a user follows. The collections themselves are
+-- repo content (data/collections/*.json); this is the user-data half.
+CREATE TABLE IF NOT EXISTS collection_follows (
+    user_id     TEXT NOT NULL,
+    slug        TEXT NOT NULL,
+    followed_at TEXT NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (user_id, slug)
+);
+CREATE INDEX IF NOT EXISTS idx_follow_user
+    ON collection_follows(user_id);
 """
 
 
@@ -634,3 +645,42 @@ async def prune_impressions(retention_days: int = 90) -> int:
         )
         await conn.commit()
         return cur.rowcount
+
+
+# ── Collection follows ───────────────────────────────────────────────────────
+#
+# Which curated collections a user follows. The collections themselves live in
+# the repo (see app/collections_svc.py); this is the user-data half, so it is
+# replicated by turso_sync.
+
+async def follow_collection(user_id: str, slug: str) -> None:
+    if not user_id or not slug:
+        return
+    async with aiosqlite.connect(DB_PATH) as conn:
+        await conn.execute(
+            "INSERT INTO collection_follows (user_id, slug, followed_at) "
+            "VALUES (?, ?, datetime('now')) "
+            "ON CONFLICT(user_id, slug) DO UPDATE SET followed_at = datetime('now')",
+            (user_id, slug),
+        )
+        await conn.commit()
+
+
+async def unfollow_collection(user_id: str, slug: str) -> None:
+    if not user_id or not slug:
+        return
+    async with aiosqlite.connect(DB_PATH) as conn:
+        await conn.execute(
+            "DELETE FROM collection_follows WHERE user_id = ? AND slug = ?",
+            (user_id, slug),
+        )
+        await conn.commit()
+
+
+async def get_followed_slugs(user_id: str) -> set[str]:
+    if not user_id:
+        return set()
+    async with aiosqlite.connect(DB_PATH) as conn:
+        cur = await conn.execute(
+            "SELECT slug FROM collection_follows WHERE user_id = ?", (user_id,))
+        return {r[0] for r in await cur.fetchall()}

app/main.py

@@ -18,7 +18,8 @@ from fastapi.staticfiles import StaticFiles
 from app import db
 from app.config import APP_TITLE, COOKIE_NAME
 from app.templates_env import templates
-from app.routers import search, events, recommendations, saved, onboarding, health
+from app.routers import (search, events, recommendations, saved, onboarding,
+                         health, collections)
 
 
 @asynccontextmanager
@@ -114,6 +115,7 @@ app.include_router(recommendations.router)
 app.include_router(saved.router)
 app.include_router(onboarding.router)
 app.include_router(health.router)
+app.include_router(collections.router)
 # researchit-space (3D map client) JSON API. Guarded the same way as the Turso
 # sync and BGE-M3 warmup above: this router is additive, and a fault inside it
 # must never stop the main app from serving.

app/routers/collections.py

@@ -0,0 +1,255 @@
+"""
+Curated reading collections.
+
+GET  /collections                     – index of every curated collection
+GET  /collections/{slug}              – anchors, plus medoid-matched recent work
+POST /api/collections/{slug}/follow   – seed the user's profile from the anchors
+POST /api/collections/{slug}/unfollow
+
+Why this exists
+---------------
+Cold start asks a new user to pick arXiv categories, but `cs.LG` is ~302k
+papers -- far too coarse to retrieve against. A collection is a much sharper
+signal, and following one replays its anchors through the ordinary save path,
+which puts the user straight past the >=5-save threshold into Tier 1
+multi-interest clustering. It skips the weakest part of the pipeline entirely.
+
+Semantic Scholar's Research Feeds work the same way -- the feed is seeded from
+a curated Library folder, with a stated minimum of "5 relevant papers... and 3
+non-relevant". Every collection here carries at least 6 anchors, so one click
+clears that budget.
+"""
+import uuid
+
+from fastapi import APIRouter, Cookie, Request
+from fastapi.responses import HTMLResponse
+
+from app import arxiv_svc, collections_svc, db, turso_svc, user_state as us
+from app.config import COOKIE_NAME
+from app.templates_env import templates
+
+router = APIRouter()
+
+
+async def _hydrate(arxiv_ids: list[str], state) -> dict[str, dict]:
+    """arxiv_id -> metadata dict, with saved/dismissed flags for the card."""
+    if not arxiv_ids:
+        return {}
+    meta = await turso_svc.fetch_metadata_batch(arxiv_ids)
+    missing = [a for a in arxiv_ids if a not in meta]
+    if missing:
+        try:
+            meta.update(await arxiv_svc.fetch_metadata_batch(missing))
+        except Exception as e:
+            print(f"[collections] arXiv fallback failed for {len(missing)}: {e}")
+    try:
+        await db.cache_turso_metadata_batch(list(meta.values()))
+    except Exception as e:
+        print(f"[collections] metadata cache write skipped: {e}")
+
+    saved = set(state.positive_list) if state else set()
+    for aid, m in meta.items():
+        m["saved"] = aid in saved
+        m["dismissed"] = False
+    return meta
+
+
+@router.get("/collections", response_class=HTMLResponse)
+async def collections_index(
+    request: Request,
+    user_id: str | None = Cookie(default=None, alias=COOKIE_NAME),
+):
+    user_id = user_id or str(uuid.uuid4())
+    cols = collections_svc.load_all()
+    followed = await db.get_followed_slugs(user_id)
+
+    # Preview the first three titles per collection, the same two-tier
+    # index -> detail shape Hugging Face Collections uses. Titles only: this
+    # page must stay one metadata round trip regardless of collection count.
+    preview_ids = [a["id"] for c in cols for a in c["anchors"][:3]]
+    meta = await turso_svc.fetch_metadata_batch(preview_ids) if preview_ids else {}
+
+    view = []
+    for c in cols:
+        previews = [
+            (meta.get(a["id"]) or {}).get("title", "").strip()
+            for a in c["anchors"][:3]
+        ]
+        view.append({
+            **c,
+            "previews": [p for p in previews if p],
+            "following": c["slug"] in followed,
+        })
+
+    resp = templates.TemplateResponse(
+        request, "collections.html", {"collections": view},
+    )
+    resp.set_cookie(COOKIE_NAME, user_id, max_age=365 * 24 * 3600, httponly=True)
+    return resp
+
+
+@router.get("/collections/{slug}", response_class=HTMLResponse)
+async def collection_detail(
+    slug: str,
+    request: Request,
+    user_id: str | None = Cookie(default=None, alias=COOKIE_NAME),
+):
+    user_id = user_id or str(uuid.uuid4())
+    col = collections_svc.get(slug)
+    if col is None:
+        resp = templates.TemplateResponse(
+            request, "collections.html",
+            {"collections": [], "not_found": slug}, status_code=404,
+        )
+        resp.set_cookie(COOKIE_NAME, user_id, max_age=365 * 24 * 3600, httponly=True)
+        return resp
+
+    state = await us.ensure_loaded(user_id)
+    anchor_ids = [a["id"] for a in col["anchors"]]
+
+    # The extension is best-effort. A vector-store hiccup should cost the
+    # "recent work" section, never the curated list -- which is the part with
+    # editorial value and the part that works with no network at all.
+    try:
+        extended_ids = await collections_svc.extend(slug, exclude=us.all_seen(user_id))
+    except Exception as e:
+        print(f"[collections] extend failed for {slug}: {e}")
+        extended_ids = []
+
+    meta = await _hydrate(anchor_ids + extended_ids, state)
+
+    anchors = []
+    for i, a in enumerate(col["anchors"]):
+        m = meta.get(a["id"])
+        if m:
+            anchors.append({**m, "note": a["note"], "ordinal": i + 1})
+
+    extended = [meta[a] for a in extended_ids if a in meta]
+    followed = await db.get_followed_slugs(user_id)
+
+    resp = templates.TemplateResponse(
+        request, "collection_detail.html",
+        {
+            "collection": col,
+            "anchors": anchors,
+            "extended": extended,
+            "following": slug in followed,
+        },
+    )
+    resp.set_cookie(COOKIE_NAME, user_id, max_age=365 * 24 * 3600, httponly=True)
+    return resp
+
+
+@router.post("/api/collections/{slug}/follow", response_class=HTMLResponse)
+async def follow(
+    slug: str,
+    request: Request,
+    user_id: str | None = Cookie(default=None, alias=COOKIE_NAME),
+):
+    """Seed the user's profile from a collection's anchors.
+
+    Each anchor goes through the ordinary save path, so the EWMA update, the
+    interaction log and the clustering threshold all behave exactly as they do
+    for a hand-saved paper. No separate code path means no separate bugs, and
+    the profile a follow produces is indistinguishable from one built by hand.
+    """
+    user_id = user_id or str(uuid.uuid4())
+    col = collections_svc.get(slug)
+    if col is None:
+        return _fragment(request, user_id, None, False, 0)
+
+    ids = [a["id"] for a in col["anchors"]]
+    state = await us.ensure_loaded(user_id)
+    already = set(state.positive_list)
+    seeded = 0
+    vectorised = 0
+
+    for pos, aid in enumerate(ids):
+        if aid in already:
+            continue
+        try:
+            if await _save_one(user_id, aid, pos, slug):
+                vectorised += 1
+            seeded += 1
+        except Exception as e:
+            # One unresolvable paper must not abandon the rest of the seed.
+            print(f"[collections] seeding {aid} from {slug} failed: {e}")
+
+    # Saving and profile-seeding are different things, and only the second one
+    # makes the feed change. If the vector store cannot resolve the anchors the
+    # follow still "works" -- papers land in the library -- while doing nothing
+    # at all to recommendations. Say so loudly rather than let it pass.
+    #
+    # The usual cause is a partially configured vector store. A dev machine
+    # with only the primary shard set resolves nothing after ~2021, so every
+    # modern collection seeds zero vectors while looking fine.
+    if seeded and vectorised < seeded:
+        print(f"[collections] {slug}: seeded {seeded} saves but only {vectorised} "
+              f"vectors -- profile is under-trained. Check shard configuration.")
+
+    await db.follow_collection(user_id, slug)
+    return _fragment(request, user_id, col, True, seeded)
+
+
+@router.post("/api/collections/{slug}/unfollow", response_class=HTMLResponse)
+async def unfollow(
+    slug: str,
+    request: Request,
+    user_id: str | None = Cookie(default=None, alias=COOKIE_NAME),
+):
+    """Stop following.
+
+    Deliberately does NOT unsave the anchors or rewind the profile: the EWMA is
+    a lossy running average with no exact inverse, so "undoing" a follow would
+    leave a permanent smudge rather than restoring the previous state. The
+    papers stay in the library, where the user can remove them individually.
+    """
+    user_id = user_id or str(uuid.uuid4())
+    await db.unfollow_collection(user_id, slug)
+    return _fragment(request, user_id, collections_svc.get(slug), False, 0)
+
+
+async def _save_one(user_id: str, arxiv_id: str, position: int, slug: str) -> bool:
+    """Record one anchor exactly as events.py records a manual save.
+
+    Returns True if the EWMA profile was actually updated -- i.e. the vector
+    store resolved this paper. A save without a vector is a library entry that
+    teaches the recommender nothing, and the caller needs to tell those apart.
+    """
+    import numpy as np
+    from app import qdrant_svc
+    from app.recommend import profiles
+
+    await db.log_interaction(
+        user_id=user_id,
+        paper_id=arxiv_id,
+        event_type="save",
+        source="collection",
+        position=position,
+        query_id=f"collection:{slug}",
+        ranker_version="collection_seed",
+        candidate_source=f"collection:{slug}",
+        cluster_id=None,
+        # Deterministic by construction: following a collection shows exactly
+        # these papers, so the propensity genuinely is 1.0 (CLAUDE.md 3.11).
+        propensity=1.0,
+        policy_id="collection_seed",
+    )
+    us.record_positive(user_id, arxiv_id)
+
+    vectors = await qdrant_svc.get_paper_vectors([arxiv_id])
+    vec = vectors.get(arxiv_id)
+    if not vec:
+        return False
+    await profiles.update_on_save(user_id, np.asarray(vec, dtype=np.float32))
+    return True
+
+
+def _fragment(request: Request, user_id: str, col: dict | None,
+              following: bool, seeded: int):
+    resp = templates.TemplateResponse(
+        request, "partials/follow_button.html",
+        {"collection": col, "following": following, "seeded": seeded},
+    )
+    resp.set_cookie(COOKIE_NAME, user_id, max_age=365 * 24 * 3600, httponly=True)
+    return resp

app/static/styles.css

@@ -735,3 +735,106 @@ a.card-title:hover { color: var(--accent); }
   }
   .card.is-leaving { animation: none; display: none; }
 }
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   COLLECTIONS
+   Curated reading tracks. Two surfaces: an index that has to answer "is this
+   my track?" at a glance, and a detail view whose job is to keep editorial
+   curation visually distinct from vector-matched extension.
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+.sec-sub {
+  font-size: .9rem; color: var(--text-2);
+  max-width: 44ch; margin: -.35rem 0 1.4rem;
+}
+
+.coll-list { display: flex; flex-direction: column; gap: .9rem; }
+
+.coll-card {
+  background: var(--surface); border: 1px solid var(--border);
+  border-radius: var(--radius); padding: 1.1rem 1.15rem 1rem;
+  box-shadow: var(--shadow-1);
+}
+.coll-card:hover { border-color: var(--border-2); }
+
+.coll-card-head {
+  display: flex; align-items: baseline; justify-content: space-between;
+  gap: .8rem; margin-bottom: .35rem;
+}
+.coll-title {
+  font-family: var(--font-read); font-size: 1.12rem; font-weight: 600;
+  letter-spacing: -.012em; line-height: 1.25; text-wrap: balance;
+}
+.coll-title a { color: inherit; text-decoration: none; }
+.coll-title a:hover { text-decoration: underline; text-underline-offset: 2px; }
+
+.coll-count {
+  font-family: var(--font-mono); font-size: .68rem; letter-spacing: .04em;
+  color: var(--text-3); white-space: nowrap; font-variant-numeric: tabular-nums;
+}
+
+.coll-blurb { font-size: .89rem; color: var(--text-2); max-width: 56ch; }
+.coll-blurb--lg { font-size: .96rem; margin-top: .3rem; }
+
+/* Preview titles. Three, per the two-tier index -> detail pattern: enough to
+   recognise the track, not enough to start reading it here. */
+.coll-preview {
+  list-style: none; margin: .7rem 0 .9rem; padding: 0;
+  display: flex; flex-direction: column; gap: .18rem;
+  border-left: 2px solid var(--border); padding-left: .75rem;
+}
+.coll-preview li {
+  font-size: .84rem; color: var(--text-3);
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+.coll-preview .coll-more { color: var(--text-3); opacity: .8; font-style: italic; }
+
+.coll-actions { display: flex; align-items: center; gap: .5rem; flex-wrap: wrap; }
+
+.follow-wrap { display: inline-flex; align-items: center; gap: .6rem; flex-wrap: wrap; }
+.btn-following {
+  background: var(--accent-bg); color: var(--accent); border-color: var(--accent-br);
+}
+.btn-following:hover { background: var(--surface-2); }
+.follow-note { font-size: .8rem; color: var(--text-2); }
+
+/* ── Detail ───────────────────────────────────────────────────────────────── */
+
+.coll-hero { padding: .4rem 0 1.6rem; border-bottom: 1px solid var(--border); margin-bottom: 1.5rem; }
+.back-link {
+  display: inline-block; font-size: .82rem; color: var(--text-3);
+  text-decoration: none; margin-bottom: .6rem;
+}
+.back-link:hover { color: var(--text); }
+.coll-hero .sec-title { font-family: var(--font-read); font-size: 1.6rem; font-weight: 600; }
+.coll-hero-actions {
+  display: flex; align-items: center; gap: .9rem; flex-wrap: wrap; margin-top: 1rem;
+}
+
+.sec-head--sub { margin-top: 2.2rem; padding-bottom: .5rem; border-bottom: 1px solid var(--border); }
+.sec-title--sm {
+  font-family: var(--font-ui); font-size: .74rem; font-weight: 620;
+  letter-spacing: .09em; text-transform: uppercase; color: var(--text-3);
+}
+.sec-note { font-size: .76rem; color: var(--text-3); font-style: italic; }
+
+/* Anchors carry an ordinal and a curator note. The ordinal is deliberately
+   quiet -- reading order is information, but it is not the headline. */
+.anchor-row { display: flex; gap: .85rem; align-items: flex-start; }
+.anchor-ord {
+  flex: 0 0 1.4rem; font-family: var(--font-mono); font-size: .78rem;
+  color: var(--text-3); text-align: right; padding-top: 1.05rem;
+  font-variant-numeric: tabular-nums;
+}
+.anchor-body { flex: 1 1 auto; min-width: 0; }
+.anchor-note {
+  font-family: var(--font-read); font-size: .89rem; line-height: 1.5;
+  color: var(--text-2); margin: 0 0 .4rem; padding-left: .1rem;
+  max-width: 60ch;
+}
+.feed--anchored { gap: 1.1rem; }
+
+@media (max-width: 34rem) {
+  .anchor-ord { display: none; }
+  .coll-card-head { flex-direction: column; gap: .2rem; }
+}

app/templates/base.html

@@ -62,6 +62,7 @@
 
         <nav class="nav" aria-label="Main">
           <a href="/" class="nav-link" {% if path == '/' %}aria-current="page"{% endif %}>Feed</a>
+          <a href="/collections" class="nav-link" {% if path.startswith('/collections') %}aria-current="page"{% endif %}>Collections</a>
           <a href="/search" class="nav-link" {% if path.startswith('/search') %}aria-current="page"{% endif %}>Search</a>
           <a href="/saved" class="nav-link" {% if path.startswith('/saved') %}aria-current="page"{% endif %}>Library</a>
           {% if space_app_url %}
@@ -102,6 +103,17 @@
       </svg>
       <span>Feed</span>
     </a>
+    <a href="/collections" class="botnav-item" {% if path.startswith('/collections') %}aria-current="page"{% endif %}>
+      {# Stacked layers: a set of things gathered, distinct from the single
+         bookmark used for Library. #}
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7"
+           stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+        <path d="m12 3 8.5 4.5L12 12 3.5 7.5z" />
+        <path d="m3.5 12 8.5 4.5 8.5-4.5" opacity=".55" />
+        <path d="m3.5 16.5 8.5 4.5 8.5-4.5" opacity=".3" />
+      </svg>
+      <span>Collections</span>
+    </a>
     <a href="/search" class="botnav-item" {% if path.startswith('/search') %}aria-current="page"{% endif %}>
       <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7"
            stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">

app/templates/collection_detail.html

@@ -0,0 +1,75 @@
+{% extends "base.html" %}
+
+{% block title %}{{ collection.title }} — ResearchIT{% endblock %}
+
+{#
+  Collection detail.
+
+  The one decision that matters here is the seam. A collection holds two kinds
+  of paper: anchors, which are an editorial judgement, and extended papers,
+  which are whatever currently sits nearest the collection medoid. Presenting
+  them as one list would quietly pass off vector search as curation, so they
+  get separate headed sections and the extended one says where it came from.
+
+  Anchors reuse partials/paper_card.html so save/pass and all the Phase 4.5 /
+  6.5 instrumentation keep working unchanged; the ordinal and the note are
+  rendered around the card rather than inside it.
+#}
+
+{% block content %}
+<div class="wrap wrap--feed">
+
+  <div class="coll-hero">
+    <a href="/collections" class="back-link">← Collections</a>
+    <h1 class="sec-title">{{ collection.title }}</h1>
+    <p class="coll-blurb coll-blurb--lg">{{ collection.blurb }}</p>
+    <div class="coll-hero-actions">
+      <span class="coll-count">{{ collection.count }} curated{% if extended %} · extends automatically{% endif %}</span>
+      {% include "partials/follow_button.html" %}
+    </div>
+  </div>
+
+  {% if anchors %}
+    <div class="sec-head sec-head--sub">
+      <h2 class="sec-title sec-title--sm">Curated</h2>
+    </div>
+
+    <div class="feed feed--anchored">
+      {% for paper in anchors %}
+        <div class="anchor-row">
+          <div class="anchor-ord" aria-hidden="true">{{ paper.ordinal }}</div>
+          <div class="anchor-body">
+            {% if paper.note %}
+              <p class="anchor-note">{{ paper.note }}</p>
+            {% endif %}
+            {% set position = loop.index0 %}
+            {% set source = "collection" %}
+            {% include "partials/paper_card.html" %}
+          </div>
+        </div>
+      {% endfor %}
+    </div>
+  {% else %}
+    <div class="empty">
+      <p class="empty-title">Could not load this collection’s papers</p>
+      <p class="empty-body">The metadata store did not return them. Try again shortly.</p>
+    </div>
+  {% endif %}
+
+  {% if extended %}
+    <div class="sec-head sec-head--sub">
+      <h2 class="sec-title sec-title--sm">Recent work in this area</h2>
+      <span class="sec-note">Matched to this collection, not hand-picked</span>
+    </div>
+
+    <div class="feed">
+      {% for paper in extended %}
+        {% set position = anchors | length + loop.index0 %}
+        {% set source = "collection_extended" %}
+        {% include "partials/paper_card.html" %}
+      {% endfor %}
+    </div>
+  {% endif %}
+
+</div>
+{% endblock %}

app/templates/collections.html

@@ -0,0 +1,71 @@
+{% extends "base.html" %}
+
+{% block title %}Collections — ResearchIT{% endblock %}
+
+{#
+  Collection index.
+
+  Two-tier index -> detail, previewing three titles per collection. Anything
+  more turns a browsing page into a wall of abstracts, and the preview exists
+  to answer "is this the track I want", not to be read.
+#}
+
+{% block content %}
+<div class="wrap wrap--feed">
+
+  <div class="sec-head">
+    <h1 class="sec-title">Collections</h1>
+  </div>
+
+  {% if not_found %}
+    <div class="empty">
+      <p class="empty-title">No collection called “{{ not_found }}”</p>
+      <p class="empty-body">It may have been renamed. Everything available is listed below.</p>
+    </div>
+  {% endif %}
+
+  {% if collections %}
+    <p class="sec-sub">
+      Curated starting points. Follow one and the feed learns from it
+      immediately — no need to save papers one at a time first.
+    </p>
+
+    <div class="coll-list">
+      {% for c in collections %}
+        <article class="coll-card">
+          <div class="coll-card-head">
+            <h2 class="coll-title">
+              <a href="/collections/{{ c.slug }}">{{ c.title }}</a>
+            </h2>
+            <span class="coll-count">{{ c.count }} papers</span>
+          </div>
+
+          <p class="coll-blurb">{{ c.blurb }}</p>
+
+          {% if c.previews %}
+            <ul class="coll-preview">
+              {% for t in c.previews %}<li>{{ t }}</li>{% endfor %}
+              {% if c.count > c.previews | length %}
+                <li class="coll-more">+ {{ c.count - (c.previews | length) }} more</li>
+              {% endif %}
+            </ul>
+          {% endif %}
+
+          <div class="coll-actions">
+            <a href="/collections/{{ c.slug }}" class="btn btn-sm">Open</a>
+            {% with collection = c, following = c.following, seeded = 0 %}
+              {% include "partials/follow_button.html" %}
+            {% endwith %}
+          </div>
+        </article>
+      {% endfor %}
+    </div>
+  {% elif not not_found %}
+    <div class="empty">
+      <p class="empty-title">No collections yet</p>
+      <p class="empty-body">Curated collections live in <code>data/collections/</code>.</p>
+    </div>
+  {% endif %}
+
+</div>
+{% endblock %}

app/templates/partials/follow_button.html

@@ -0,0 +1,42 @@
+{#
+  Follow / Following toggle for a collection.
+
+  Also the HTMX response fragment for the follow and unfollow endpoints, so the
+  button swaps itself and there is exactly one definition of what the control
+  looks like in each state.
+
+  Expects:
+    collection  dict with .slug (may be None if the slug was unknown)
+    following   bool
+    seeded      int — papers added to the profile by this click, 0 otherwise
+#}
+{% if collection %}
+  <span class="follow-wrap" id="follow-{{ collection.slug }}">
+    {% if following %}
+      <button type="button"
+              class="btn btn-sm btn-following"
+              hx-post="/api/collections/{{ collection.slug }}/unfollow"
+              hx-target="closest .follow-wrap"
+              hx-swap="outerHTML"
+              aria-label="Stop following {{ collection.title | default(collection.slug) }}">
+        Following ✓
+      </button>
+      {% if seeded %}
+        {# Say what actually happened. "Following" alone hides the fact that
+           the feed just changed underneath them. #}
+        <span class="follow-note" role="status">
+          {{ seeded }} paper{{ "s" if seeded != 1 }} added to your library — your feed will reflect this now.
+        </span>
+      {% endif %}
+    {% else %}
+      <button type="button"
+              class="btn btn-sm btn-primary"
+              hx-post="/api/collections/{{ collection.slug }}/follow"
+              hx-target="closest .follow-wrap"
+              hx-swap="outerHTML"
+              aria-label="Follow {{ collection.title | default(collection.slug) }}">
+        Follow
+      </button>
+    {% endif %}
+  </span>
+{% endif %}

tests/test_collections.py

@@ -0,0 +1,241 @@
+"""
+Tests for curated reading collections.
+
+No network: the vector store and metadata layer are stubbed, so what is under
+test is the loading, the seeding contract and the honesty of the follow
+response -- not Qdrant.
+"""
+import json
+
+import numpy as np
+import pytest
+from fastapi.testclient import TestClient
+
+import app.db as db_mod
+from app import collections_svc
+
+
+@pytest.fixture
+def repo(tmp_path, monkeypatch):
+    """A collections directory with two known collections."""
+    d = tmp_path / "collections"
+    d.mkdir()
+    (d / "alpha.json").write_text(json.dumps({
+        "slug": "alpha", "title": "Alpha Track", "blurb": "First.",
+        "anchors": [{"id": f"2401.{i:05d}", "note": f"note {i}"} for i in range(6)],
+    }))
+    (d / "beta.json").write_text(json.dumps({
+        "slug": "beta", "title": "Beta Track", "blurb": "Second.",
+        "anchors": [{"id": "1706.03762", "note": "the transformer"}],
+    }))
+    monkeypatch.setattr(collections_svc, "COLLECTIONS_DIR", str(d))
+    collections_svc.load_all.cache_clear()
+    yield d
+    collections_svc.load_all.cache_clear()
+
+
+# ── Loading ──────────────────────────────────────────────────────────────────
+
+def test_loads_and_sorts_by_title(repo):
+    cols = collections_svc.load_all()
+    assert [c["slug"] for c in cols] == ["alpha", "beta"]
+    assert cols[0]["count"] == 6
+
+
+def test_lookup_by_slug(repo):
+    assert collections_svc.get("alpha")["title"] == "Alpha Track"
+    assert collections_svc.get("nope") is None
+    assert collections_svc.anchor_ids("beta") == ["1706.03762"]
+
+
+def test_a_malformed_file_does_not_break_the_index(repo):
+    """One bad edit must not take the page down for every other collection."""
+    (repo / "broken.json").write_text("{ this is not json")
+    (repo / "empty.json").write_text(json.dumps({"slug": "empty", "anchors": []}))
+    collections_svc.load_all.cache_clear()
+
+    slugs = [c["slug"] for c in collections_svc.load_all()]
+    assert slugs == ["alpha", "beta"]
+
+
+def test_missing_directory_is_survivable(monkeypatch, tmp_path):
+    monkeypatch.setattr(collections_svc, "COLLECTIONS_DIR", str(tmp_path / "nope"))
+    collections_svc.load_all.cache_clear()
+    assert collections_svc.load_all() == []
+    collections_svc.load_all.cache_clear()
+
+
+# ── The shipped content ──────────────────────────────────────────────────────
+
+def test_shipped_collections_are_wellformed():
+    """Guards the real data/collections/*.json, not a fixture."""
+    collections_svc.load_all.cache_clear()
+    cols = collections_svc.load_all()
+    assert len(cols) >= 8, "expected the eight curated tracks"
+
+    for c in cols:
+        # Semantic Scholar's stated cold-start budget is 5 positives; every
+        # track must clear it in a single click, and clear Tier 1's >=5 too.
+        assert c["count"] >= 6, f"{c['slug']} has too few anchors to seed a profile"
+        assert c["blurb"], f"{c['slug']} has no blurb"
+        for a in c["anchors"]:
+            assert a["note"], f"{c['slug']}/{a['id']} has no curator note"
+            # arXiv ids are strings and keep their leading zeros (CLAUDE.md 3.9)
+            assert isinstance(a["id"], str) and "." in a["id"]
+
+    ids = [a["id"] for c in cols for a in c["anchors"]]
+    assert len(ids) == len(set(ids)), "an anchor appears in two collections"
+
+
+# ── Routes ───────────────────────────────────────────────────────────────────
+
+@pytest.fixture
+def client(tmp_path, monkeypatch, repo):
+    import asyncio
+
+    import app.config as cfg
+
+    path = str(tmp_path / "coll.db")
+    monkeypatch.setattr(cfg, "DB_PATH", path)
+    monkeypatch.setattr(db_mod, "DB_PATH", path)
+
+    import app.user_state as us
+    us._cache.clear()
+
+    import app.turso_svc as turso
+
+    async def fake_meta(ids):
+        return {i: {"arxiv_id": i, "title": f"Paper {i}", "abstract": "abs.",
+                    "authors": "[]", "category": "cs.LG", "published": "2024-01-01",
+                    "year": 2024, "citation_count": 3} for i in ids}
+
+    monkeypatch.setattr(turso, "fetch_metadata_batch", fake_meta)
+
+    async def no_extend(slug, limit=12, exclude=None):
+        return []
+
+    monkeypatch.setattr(collections_svc, "extend", no_extend)
+
+    asyncio.run(db_mod.init_db())
+    from app.main import app
+    with TestClient(app) as c:
+        yield c
+
+
+def test_index_lists_collections(client):
+    r = client.get("/collections")
+    assert r.status_code == 200
+    assert "Alpha Track" in r.text and "Beta Track" in r.text
+
+
+def test_detail_renders_anchors_and_notes(client):
+    r = client.get("/collections/alpha")
+    assert r.status_code == 200
+    assert "Alpha Track" in r.text
+    assert "note 0" in r.text, "curator note missing from the page"
+
+
+def test_unknown_slug_is_404_not_500(client):
+    assert client.get("/collections/does-not-exist").status_code == 404
+
+
+# ── Following ────────────────────────────────────────────────────────────────
+
+def test_following_seeds_the_profile(client, monkeypatch):
+    """The point of the feature: one click puts a user past the Tier 1 threshold."""
+    import app.qdrant_svc as qs
+
+    async def fake_vectors(ids):
+        rng = np.random.default_rng(0)
+        return {i: rng.random(1024, dtype=np.float32).tolist() for i in ids}
+
+    monkeypatch.setattr(qs, "get_paper_vectors", fake_vectors)
+
+    r = client.post("/api/collections/alpha/follow")
+    assert r.status_code == 200
+    assert "Following" in r.text
+    assert "6 papers added" in r.text
+
+    import asyncio
+    import sqlite3
+
+    uid = client.cookies.get("arxiv_user_id")
+    rows = asyncio.run(db_mod.get_user_interactions(uid, event_types=["save"]))
+    assert len(rows) == 6
+
+    # Instrumentation must survive the seeding path (CLAUDE.md §3.11).
+    # get_user_interactions only selects three columns, so read the table.
+    conn = sqlite3.connect(db_mod.DB_PATH)
+    tagged = conn.execute(
+        "SELECT candidate_source, policy_id, propensity, source FROM interactions "
+        "WHERE user_id = ? AND event_type = 'save'", (uid,)).fetchall()
+    conn.close()
+    assert len(tagged) == 6
+    assert all(t == ("collection:alpha", "collection_seed", 1.0, "collection")
+               for t in tagged)
+
+
+def test_following_is_idempotent(client, monkeypatch):
+    import app.qdrant_svc as qs
+
+    async def fake_vectors(ids):
+        return {i: np.zeros(1024, dtype=np.float32).tolist() for i in ids}
+
+    monkeypatch.setattr(qs, "get_paper_vectors", fake_vectors)
+
+    client.post("/api/collections/alpha/follow")
+    client.post("/api/collections/alpha/follow")
+
+    import asyncio
+    rows = asyncio.run(db_mod.get_user_interactions(
+        client.cookies.get("arxiv_user_id"), event_types=["save"]))
+    assert len(rows) == 6, "a second follow re-saved the same anchors"
+
+
+def test_follow_survives_a_vector_store_outage(client, monkeypatch):
+    """Papers must still reach the library when Qdrant is unavailable.
+
+    The profile will be under-trained, which the server logs -- but the follow
+    must not 500.
+    """
+    import app.qdrant_svc as qs
+
+    async def boom(ids):
+        raise RuntimeError("qdrant down")
+
+    monkeypatch.setattr(qs, "get_paper_vectors", boom)
+
+    r = client.post("/api/collections/alpha/follow")
+    assert r.status_code == 200
+
+
+def test_unfollow_does_not_unsave(client, monkeypatch):
+    """The EWMA has no exact inverse, so unfollowing cannot rewind the profile.
+
+    Anything else would leave a permanent smudge while claiming to undo.
+    """
+    import app.qdrant_svc as qs
+
+    async def fake_vectors(ids):
+        return {i: np.zeros(1024, dtype=np.float32).tolist() for i in ids}
+
+    monkeypatch.setattr(qs, "get_paper_vectors", fake_vectors)
+
+    client.post("/api/collections/alpha/follow")
+    r = client.post("/api/collections/alpha/unfollow")
+    assert r.status_code == 200
+    assert "Follow" in r.text
+
+    import asyncio
+    uid = client.cookies.get("arxiv_user_id")
+    assert await_len(asyncio, uid) == 6
+    assert asyncio.run(db_mod.get_followed_slugs(uid)) == set()
+
+
+def await_len(asyncio_mod, uid):
+    return len(asyncio_mod.run(
+        db_mod.get_user_interactions(uid, event_types=["save"])))
+
+
+def test_unknown_slug_follow_is_not_an_error(client):
+    assert client.post("/api/collections/ghost/follow").status_code == 200