Search published products using semantic vector embeddings. This is intended for "concerns" style queries (e.g. acne, hyperpigmentation, hydration) and returns products ranked by cosine similarity to the query embedding — strongest match first.

Default behavior (no limit, no min_similarity): every published product that matches the SQL filters (vendor, product_ids) is scored and returned in ranked order. Ranking does the work — the frontend can render the top N and "show more" the tail without a second call. No server-side cap, no pagination. Same query returns the same ordering on repeat calls (deterministic).

Optional knobs:

• limit — client-side trim. Returns the top N by similarity. Omit to get everything.
• min_similarity — hard floor on cosine similarity. Products below the floor are dropped server-side. When nothing clears the floor, the response is data: [] (no synthetic-fit fallback). Defaults to no floor (config value embeddings.search.min_similarity, currently -1.0). Recommended values depend on catalog density and embedding model — start at -1 and tighten only if the long tail is noisy for your use case.

Scoping: restrict to a single vendor (vendor_id) or an explicit allow-list (product_ids). For vendor/staff users, results are automatically restricted to the authenticated vendor regardless of any vendor_id they send.

fit_percentage in each result is round(similarity × 100). Absolute values are catalog-relative — in a focused single-domain catalog, even the genuine top match may score in the 60s-70s. Treat fit_percentage as a ranking signal, not an absolute quality score.