Related suggestions (RELATED-VEC)

Sketch · _catalog/RELATED-VEC.md · docs/plans/2026-09-16-related-vec-enablement.md · Technologies

Problem

Entity pages show declared edges only. A catalog.db vec table was stubbed and never built, while _corpus already embeds the same packs. Visitors have no “maybe same cluster” strip.

Decision

Do not embed twice. Reuse _corpus/corpus.sqlite for recall. Keep catalog edges as authority. UI label: Suggested · not a catalog edge.

Target flow

RELATED-VEC enablement flow

Aside bands

Declared (unchanged)

Features · Same cell · Stack · Design × AI — from catalog / design graph.

Suggested (new)

Corpus KNN neighbours collapsed by slug. Cap 6. Hide if fewer than 2 after filters.

Rollout waves

  1. 0 — Sketch (this page)
  2. 1 — related_for.py + JSON export for technologies
  3. 2 — Aside UI on 5 pilot slugs (flagged)
  4. 3 — All technologies with corpus coverage
  5. 4 — Features (+ optional blog cites)

Non-goals

  • Do not auto-close G_* gaps from distance.
  • Do not write maps_to / alternative_to / in_stack from KNN.
  • Do not put a second vec table in catalog.db.
  • Do not free-vector-only (LOCK: filter, then KNN).

Open operator rulings

  • Build-time JSON vs sidecar API for v1? Assumed JSON until overturned.
  • Distance scores: locked — titles only (no distance on Suggested chips).
  • Include tech_quote hits or README-only? Assumed README-only until overturned.

In this research

Catalog surfaces this sketch refers to. Full write-up in docs/plans.