feat: add atlas project search

app.py

@@ -30,6 +30,12 @@ from hackathon_advisor.dashboard_storage import (
     persist_refresh_artifacts,
     require_writable_cache_dir,
 )
+from hackathon_advisor.dashboard_search import (
+    DEFAULT_SEARCH_LIMIT,
+    DashboardSearchIndex,
+    normalize_query,
+    normalize_search_limit,
+)
 from hackathon_advisor.data import (
     DEFAULT_EMBEDDING_MODEL_FILE,
     DEFAULT_EMBEDDING_MODEL_REPO,
@@ -120,6 +126,7 @@ def _load_initial_runtime() -> tuple[ProjectIndex, dict[str, Any]]:
 
 
 index, dashboard_payload = _load_initial_runtime()
+dashboard_search_index = DashboardSearchIndex(index.projects, dashboard_payload)
 
 # Acceleration is automatic: on a ZeroGPU Space the GPU path uses accelerate device_map inside
 # the @spaces.GPU fork; locally the device resolves CUDA -> Apple MPS -> CPU. CPU is only used
@@ -775,14 +782,16 @@ def _format_refresh_error(error: BaseException) -> str:
 
 
 def _replace_runtime_from_files(projects_path: Path, index_path: Path, refreshed_dashboard: dict[str, Any]) -> None:
-    global index, engine, _cpu_engine, dashboard_payload
+    global index, engine, _cpu_engine, dashboard_payload, dashboard_search_index
     new_index = ProjectIndex.from_files(projects_path, index_path)
+    new_search_index = DashboardSearchIndex(new_index.projects, refreshed_dashboard)
     with _runtime_lock:
         index = new_index
         engine = AdvisorEngine(new_index, engine.planner)
         if _cpu_engine is not None:
             _cpu_engine = AdvisorEngine(new_index, _cpu_engine.planner)
         dashboard_payload = refreshed_dashboard
+        dashboard_search_index = new_search_index
 
 
 def _public_dashboard_payload(payload: dict[str, Any]) -> dict[str, Any]:
@@ -900,6 +909,34 @@ def dashboard() -> dict:
     return payload
 
 
+@app.get("/api/dashboard/search")
+def dashboard_search(q: str = "", limit: int = DEFAULT_SEARCH_LIMIT) -> dict:
+    query = normalize_query(q)
+    if not query:
+        raise HTTPException(status_code=400, detail="Search query is required.")
+    try:
+        normalized_limit = normalize_search_limit(limit)
+    except ValueError as error:
+        raise HTTPException(status_code=400, detail=str(error)) from error
+    with _runtime_lock:
+        search_index = dashboard_search_index
+        current_dashboard = dashboard_payload
+    payload = search_index.search(query, limit=normalized_limit)
+    public_points = {
+        str(point.get("id") or ""): _public_dashboard_point(point)
+        for point in current_dashboard.get("points") or []
+        if isinstance(point, dict)
+    }
+    for result in payload["results"]:
+        result["point"] = public_points.get(str(result.get("project_id") or ""), {})
+    provenance = current_dashboard.get("provenance", {})
+    payload["provenance"] = {
+        "snapshot_digest": str(provenance.get("snapshot_digest") or ""),
+        "snapshot_generated_at": str(provenance.get("snapshot_generated_at") or ""),
+    }
+    return payload
+
+
 @app.post("/api/dashboard/refresh")
 def dashboard_refresh_start(payload: dict[str, Any] | None = None) -> JSONResponse:
     try:

hackathon_advisor/dashboard_search.py

@@ -0,0 +1,388 @@
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+import math
+import re
+import unicodedata
+from typing import Any
+
+from hackathon_advisor.data import Project, public_project_summary, public_project_title
+
+
+SEARCH_SCHEMA_VERSION = 1
+SEARCH_ALGORITHM = "bm25-text-v1"
+DEFAULT_SEARCH_LIMIT = 12
+MAX_SEARCH_LIMIT = 30
+BM25_K1 = 1.35
+BM25_B = 0.72
+MAX_SNIPPET_CHARS = 170
+
+SEARCH_TOKEN_RE = re.compile(r"[\w][\w.+-]*", re.UNICODE)
+TOKEN_SPLIT_RE = re.compile(r"[._+\-/]+")
+HIGHLIGHT_BOUNDARY_RE = re.compile(r"\s+")
+
+STOPWORDS = {
+    "a",
+    "an",
+    "and",
+    "are",
+    "as",
+    "at",
+    "be",
+    "by",
+    "for",
+    "from",
+    "in",
+    "into",
+    "is",
+    "it",
+    "its",
+    "of",
+    "on",
+    "or",
+    "that",
+    "the",
+    "their",
+    "this",
+    "to",
+    "with",
+    "you",
+    "your",
+}
+
+
+@dataclass(frozen=True)
+class SearchField:
+    source: str
+    text: str
+    weight: float
+
+
+@dataclass(frozen=True)
+class SearchDocument:
+    project: Project
+    fields: tuple[SearchField, ...]
+    term_counts: Counter[str]
+    length: float
+
+
+@dataclass(frozen=True)
+class DashboardSearchHit:
+    project: Project
+    score: float
+    matched_terms: tuple[str, ...]
+    snippets: tuple[dict[str, str], ...]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "project": self.project.to_public_dict(),
+            "project_id": self.project.id,
+            "title": public_project_title(self.project.title),
+            "summary": public_project_summary(self.project.summary),
+            "url": self.project.url,
+            "score": round(self.score, 4),
+            "matched_terms": list(self.matched_terms),
+            "snippets": [dict(snippet) for snippet in self.snippets],
+        }
+
+
+class DashboardSearchIndex:
+    def __init__(self, projects: Sequence[Project], dashboard_payload: Mapping[str, Any]) -> None:
+        point_by_id = _point_by_project_id(dashboard_payload)
+        cluster_by_id = _cluster_by_id(dashboard_payload)
+        quest_label_by_id = _quest_label_by_id(dashboard_payload)
+        self.documents = tuple(
+            _build_document(
+                project,
+                point_by_id,
+                cluster_by_id,
+                quest_label_by_id,
+            )
+            for project in projects
+        )
+        if not self.documents:
+            raise ValueError("dashboard search index requires at least one project")
+        self.document_count = len(self.documents)
+        self.average_length = (
+            sum(document.length for document in self.documents) / self.document_count
+        )
+        self.document_frequency = _document_frequency(self.documents)
+        self.index_metadata = {
+            "schema_version": SEARCH_SCHEMA_VERSION,
+            "algorithm": SEARCH_ALGORITHM,
+            "document_count": self.document_count,
+        }
+
+    def search(self, query: str, limit: int = DEFAULT_SEARCH_LIMIT) -> dict[str, Any]:
+        normalized_query = normalize_query(query)
+        terms = tuple(dict.fromkeys(search_tokens(normalized_query)))
+        if not terms:
+            return {
+                "schema_version": SEARCH_SCHEMA_VERSION,
+                "algorithm": SEARCH_ALGORITHM,
+                "query": normalized_query,
+                "total": 0,
+                "results": [],
+            }
+
+        scored: list[tuple[float, SearchDocument]] = []
+        for document in self.documents:
+            score = self._score_document(document, terms, normalized_query)
+            if score > 0:
+                scored.append((score, document))
+        scored.sort(
+            key=lambda item: (
+                item[0],
+                item[1].project.likes,
+                item[1].project.title.casefold(),
+            ),
+            reverse=True,
+        )
+        raw_top_score = scored[0][0] if scored else 0.0
+        results = [
+            DashboardSearchHit(
+                project=document.project,
+                score=raw_score / raw_top_score if raw_top_score else 0.0,
+                matched_terms=tuple(
+                    term for term in terms if document.term_counts.get(term, 0) > 0
+                )[:8],
+                snippets=tuple(_snippets(document, terms)),
+            ).to_dict()
+            for raw_score, document in scored[:limit]
+        ]
+        return {
+            "schema_version": SEARCH_SCHEMA_VERSION,
+            "algorithm": SEARCH_ALGORITHM,
+            "query": normalized_query,
+            "total": len(scored),
+            "results": results,
+        }
+
+    def _score_document(
+        self,
+        document: SearchDocument,
+        terms: Sequence[str],
+        normalized_query: str,
+    ) -> float:
+        score = 0.0
+        length = max(document.length, 1.0)
+        average_length = max(self.average_length, 1.0)
+        for term in terms:
+            frequency = float(document.term_counts.get(term, 0.0))
+            if frequency <= 0:
+                continue
+            idf = self._idf(term)
+            denominator = frequency + BM25_K1 * (1.0 - BM25_B + BM25_B * length / average_length)
+            score += idf * ((frequency * (BM25_K1 + 1.0)) / denominator)
+
+        query_for_exact = normalized_query.casefold()
+        if query_for_exact:
+            title = public_project_title(document.project.title).casefold()
+            slug = document.project.slug.replace("-", " ").replace("_", " ").casefold()
+            if query_for_exact in title:
+                score += 2.0
+            if query_for_exact in slug:
+                score += 1.4
+        return score
+
+    def _idf(self, term: str) -> float:
+        frequency = self.document_frequency.get(term, 0)
+        return math.log(1.0 + (self.document_count - frequency + 0.5) / (frequency + 0.5))
+
+
+def normalize_query(query: str) -> str:
+    return " ".join(str(query or "").split())
+
+
+def normalize_search_limit(value: Any) -> int:
+    try:
+        limit = int(value)
+    except (TypeError, ValueError) as error:
+        raise ValueError("search limit must be an integer") from error
+    if not 1 <= limit <= MAX_SEARCH_LIMIT:
+        raise ValueError(f"search limit must be between 1 and {MAX_SEARCH_LIMIT}")
+    return limit
+
+
+def search_tokens(text: str) -> list[str]:
+    tokens: list[str] = []
+    normalized = unicodedata.normalize("NFKC", str(text or "")).casefold()
+    for raw_token in SEARCH_TOKEN_RE.findall(normalized):
+        for token in _token_variants(raw_token):
+            if (len(token) <= 1 and not token.isdigit()) or token in STOPWORDS:
+                continue
+            tokens.append(token)
+    return tokens
+
+
+def _token_variants(raw_token: str) -> tuple[str, ...]:
+    cleaned = raw_token.strip("._+-/")
+    if not cleaned:
+        return ()
+    parts = tuple(part for part in TOKEN_SPLIT_RE.split(cleaned) if len(part) > 1)
+    if parts and parts != (cleaned,):
+        return (cleaned, *parts)
+    return (cleaned,)
+
+
+def _document_frequency(documents: Sequence[SearchDocument]) -> dict[str, int]:
+    frequency: Counter[str] = Counter()
+    for document in documents:
+        frequency.update(document.term_counts.keys())
+    return dict(frequency)
+
+
+def _build_document(
+    project: Project,
+    point_by_id: Mapping[str, Mapping[str, Any]],
+    cluster_by_id: Mapping[str, Mapping[str, Any]],
+    quest_label_by_id: Mapping[str, str],
+) -> SearchDocument:
+    point = point_by_id.get(project.id, {})
+    fields = _project_fields(project, point, cluster_by_id, quest_label_by_id)
+    term_counts: Counter[str] = Counter()
+    for field in fields:
+        for token in search_tokens(field.text):
+            term_counts[token] += field.weight
+    return SearchDocument(
+        project=project,
+        fields=fields,
+        term_counts=term_counts,
+        length=sum(term_counts.values()),
+    )
+
+
+def _point_by_project_id(dashboard_payload: Mapping[str, Any]) -> dict[str, Mapping[str, Any]]:
+    return {
+        str(point.get("id") or ""): point
+        for point in dashboard_payload.get("points") or []
+        if isinstance(point, Mapping)
+    }
+
+
+def _project_fields(
+    project: Project,
+    point: Mapping[str, Any],
+    cluster_by_id: Mapping[str, Mapping[str, Any]],
+    quest_labels: Mapping[str, str],
+) -> tuple[SearchField, ...]:
+    cluster = cluster_by_id.get(str(point.get("cluster_id") or ""), {})
+    quest_texts = []
+    for match in point.get("quest_matches") or []:
+        if not isinstance(match, Mapping):
+            continue
+        quest = str(match.get("quest") or "")
+        quest_texts.append(
+            " ".join(
+                [
+                    quest_labels.get(quest, quest),
+                    str(match.get("evidence") or ""),
+                ]
+            ).strip()
+        )
+
+    return tuple(
+        field
+        for field in [
+            SearchField("Title", public_project_title(project.title), 4.0),
+            SearchField(
+                "Space",
+                " ".join(
+                    [
+                        project.id,
+                        project.slug,
+                        project.slug.replace("-", " ").replace("_", " "),
+                    ]
+                ),
+                3.2,
+            ),
+            SearchField("Summary", public_project_summary(project.summary), 2.4),
+            SearchField(
+                "Tags",
+                " ".join([*project.tags, *project.models, *project.datasets, project.sdk]),
+                2.0,
+            ),
+            SearchField(
+                "Cluster",
+                " ".join(
+                    [
+                        str(cluster.get("label") or ""),
+                        " ".join(str(keyword) for keyword in cluster.get("keywords") or []),
+                    ]
+                ),
+                1.4,
+            ),
+            SearchField("Quest evidence", " ".join(quest_texts), 1.6),
+            SearchField(
+                "App",
+                " ".join(
+                    [
+                        project.app_file,
+                        project.app_file_embedding_text,
+                        project.app_file_source,
+                    ]
+                ),
+                1.0,
+            ),
+            SearchField("README", project.readme_body, 0.9),
+        ]
+        if field.text.strip()
+    )
+
+
+def _cluster_by_id(dashboard_payload: Mapping[str, Any]) -> dict[str, Mapping[str, Any]]:
+    return {
+        str(cluster.get("id") or ""): cluster
+        for cluster in dashboard_payload.get("clusters") or []
+        if isinstance(cluster, Mapping)
+    }
+
+
+def _quest_label_by_id(dashboard_payload: Mapping[str, Any]) -> dict[str, str]:
+    quest_report = dashboard_payload.get("quest_report")
+    if not isinstance(quest_report, Mapping):
+        return {}
+    return {
+        str(quest.get("id") or ""): str(quest.get("label") or quest.get("id") or "")
+        for quest in quest_report.get("quests") or []
+        if isinstance(quest, Mapping)
+    }
+
+
+def _snippets(document: SearchDocument, terms: Sequence[str]) -> list[dict[str, str]]:
+    snippets: list[dict[str, str]] = []
+    seen_sources: set[str] = set()
+    for field in document.fields:
+        field_terms = set(search_tokens(field.text))
+        if not field_terms.intersection(terms):
+            continue
+        if field.source in seen_sources:
+            continue
+        snippet = _field_snippet(field.text, terms)
+        if not snippet:
+            continue
+        snippets.append({"source": field.source, "text": snippet})
+        seen_sources.add(field.source)
+        if len(snippets) >= 2:
+            break
+    return snippets
+
+
+def _field_snippet(text: str, terms: Sequence[str]) -> str:
+    cleaned = HIGHLIGHT_BOUNDARY_RE.sub(" ", str(text or "")).strip()
+    if not cleaned:
+        return ""
+    folded = unicodedata.normalize("NFKC", cleaned).casefold()
+    indexes = [folded.find(term) for term in terms if folded.find(term) >= 0]
+    center = min(indexes) if indexes else 0
+    start = max(0, center - MAX_SNIPPET_CHARS // 2)
+    end = min(len(cleaned), start + MAX_SNIPPET_CHARS)
+    start = max(0, end - MAX_SNIPPET_CHARS)
+    snippet = cleaned[start:end].strip()
+    if start > 0:
+        snippet = f"... {snippet}"
+    if end < len(cleaned):
+        snippet = f"{snippet} ..."
+    return snippet

static/app.js

@@ -5,6 +5,12 @@ const openAdvisorButton = document.querySelector("#open-advisor");
 const openAtlasButton = document.querySelector("#open-atlas");
 const refreshDashboardButton = document.querySelector("#refresh-dashboard");
 const atlasStatusEl = document.querySelector("#atlas-status");
+const atlasSearchForm = document.querySelector("#atlas-search-form");
+const atlasSearchInput = document.querySelector("#atlas-search");
+const atlasSearchClearButton = document.querySelector("#atlas-search-clear");
+const atlasSearchSectionEl = document.querySelector("#atlas-search-section");
+const atlasSearchSummaryEl = document.querySelector("#atlas-search-summary");
+const atlasSearchResultsEl = document.querySelector("#atlas-search-results");
 const atlasStatsEl = document.querySelector("#atlas-stats");
 const atlasClustersEl = document.querySelector("#atlas-clusters");
 const atlasQuestsEl = document.querySelector("#atlas-quests");
@@ -79,6 +85,13 @@ let selectedClusterId = "";
 let selectedQuestId = "";
 let selectedProjectId = "";
 let dashboardRefreshTimer = null;
+let atlasSearchQuery = "";
+let atlasSearchResults = [];
+let atlasSearchResultIds = new Set();
+let atlasSearchTimer = null;
+let atlasSearchController = null;
+let atlasSearchUnavailable = false;
+let atlasSearchBusy = false;
 
 setVoiceRecordingState("idle");
 setupViewRouting();
@@ -140,6 +153,19 @@ refreshDashboardButton?.addEventListener("click", async () => {
   await startDashboardRefresh();
 });
 
+atlasSearchForm?.addEventListener("submit", (event) => {
+  event.preventDefault();
+  runAtlasSearch(atlasSearchInput?.value || "");
+});
+
+atlasSearchInput?.addEventListener("input", () => {
+  scheduleAtlasSearch(atlasSearchInput.value || "");
+});
+
+atlasSearchClearButton?.addEventListener("click", () => {
+  clearAtlasSearch();
+});
+
 recordVoiceButton.addEventListener("click", async () => {
   await toggleVoiceRecording();
 });
@@ -226,8 +252,9 @@ async function loadDashboard() {
 }
 
 function handleDashboardError(error) {
+  console.error("Atlas could not load.", error);
   dashboardData = null;
-  if (atlasStatusEl) atlasStatusEl.textContent = `Atlas could not load: ${error.message}`;
+  if (atlasStatusEl) atlasStatusEl.textContent = "Atlas could not load.";
   if (atlasSvgEl) atlasSvgEl.innerHTML = "";
   if (atlasStatsEl) atlasStatsEl.innerHTML = "";
   if (atlasDetailEl) atlasDetailEl.innerHTML = `<p>Reload the page to try again.</p>`;
@@ -244,11 +271,9 @@ async function startDashboardRefresh() {
     renderRefreshState(data);
     scheduleRefreshPoll();
   } catch (error) {
-    if (atlasStatusEl) atlasStatusEl.textContent = `Refresh could not start: ${error.message}`;
-    if (atlasRefreshProgressEl) {
-      atlasRefreshProgressEl.hidden = false;
-      atlasRefreshProgressEl.textContent = error.message;
-    }
+    console.error("Dashboard refresh could not start.", error);
+    if (atlasStatusEl) atlasStatusEl.textContent = "Refresh could not start.";
+    if (atlasRefreshProgressEl) atlasRefreshProgressEl.hidden = true;
     refreshDashboardButton.disabled = false;
   }
 }
@@ -272,7 +297,8 @@ async function pollDashboardRefresh() {
       await loadDashboard();
     }
   } catch (error) {
-    if (atlasStatusEl) atlasStatusEl.textContent = `Refresh status unavailable: ${error.message}`;
+    console.error("Dashboard refresh status unavailable.", error);
+    if (atlasStatusEl) atlasStatusEl.textContent = "Refresh status unavailable.";
   } finally {
     if (_refreshIsSettled()) refreshDashboardButton.disabled = false;
   }
@@ -293,19 +319,20 @@ function renderRefreshState(state) {
     } else if (status === "succeeded") {
       atlasStatusEl.textContent = `Atlas refreshed: ${state.result?.project_count || "current"} projects mapped.`;
     } else if (status === "failed") {
-      atlasStatusEl.textContent = `Refresh failed: ${state.error || "unknown error"}`;
+      if (state.error) console.error("Dashboard refresh failed.", state.error);
+      atlasStatusEl.textContent = "Refresh did not complete; current map is unchanged.";
     } else if (dashboardData) {
-      atlasStatusEl.textContent = atlasProvenanceCopy(dashboardData);
+      atlasStatusEl.textContent = atlasSearchQuery ? atlasSearchStatusCopy() : atlasProvenanceCopy(dashboardData);
     }
   }
   if (atlasRefreshProgressEl) {
-    const show = status === "running" || status === "failed";
+    const show = status === "running";
     const cacheCopy = refreshQuestCacheCopy(state?.quest_cache || {});
     atlasRefreshProgressEl.hidden = !show;
     atlasRefreshProgressEl.textContent =
       status === "running"
         ? `${stage || "Working"}${cacheCopy ? ` · ${cacheCopy}` : ""} · run ${state.run_id || ""}`
-        : state.error || "";
+        : "";
   }
   if (refreshDashboardButton) refreshDashboardButton.disabled = status === "running";
 }
@@ -322,6 +349,117 @@ function refreshQuestCacheCopy(cache) {
   return `${hits} cached, ${analyzed} analyzed`;
 }
 
+function scheduleAtlasSearch(rawQuery) {
+  const query = String(rawQuery || "").trim();
+  if (atlasSearchTimer) window.clearTimeout(atlasSearchTimer);
+  if (!query) {
+    clearAtlasSearch();
+    return;
+  }
+  atlasSearchTimer = window.setTimeout(() => runAtlasSearch(query), 260);
+}
+
+async function runAtlasSearch(rawQuery) {
+  const query = String(rawQuery || "").trim();
+  if (!query) {
+    clearAtlasSearch();
+    return;
+  }
+  atlasSearchQuery = query;
+  atlasSearchUnavailable = false;
+  atlasSearchBusy = true;
+  renderAtlasSearch();
+  if (atlasSearchController) atlasSearchController.abort();
+  atlasSearchController = new AbortController();
+  try {
+    const response = await fetch(`/api/dashboard/search?q=${encodeURIComponent(query)}&limit=12`, {
+      signal: atlasSearchController.signal,
+    });
+    if (!response.ok) throw new Error(`search failed with ${response.status}`);
+    const payload = await response.json();
+    if (query !== String(atlasSearchInput?.value || "").trim()) return;
+    atlasSearchResults = payload.results || [];
+    atlasSearchResultIds = new Set(atlasSearchResults.map((result) => result.project_id).filter(Boolean));
+    atlasSearchUnavailable = false;
+    atlasSearchBusy = false;
+    if (atlasSearchResults.length) selectedProjectId = atlasSearchResults[0].project_id || selectedProjectId;
+    if (dashboardData) renderDashboard(dashboardData);
+  } catch (error) {
+    if (error.name === "AbortError") return;
+    console.error("Atlas search failed.", error);
+    atlasSearchResults = [];
+    atlasSearchResultIds = new Set();
+    atlasSearchUnavailable = true;
+    atlasSearchBusy = false;
+    if (dashboardData) renderDashboard(dashboardData);
+  }
+}
+
+function clearAtlasSearch() {
+  if (atlasSearchTimer) window.clearTimeout(atlasSearchTimer);
+  atlasSearchTimer = null;
+  if (atlasSearchController) atlasSearchController.abort();
+  atlasSearchController = null;
+  atlasSearchQuery = "";
+  atlasSearchResults = [];
+  atlasSearchResultIds = new Set();
+  atlasSearchUnavailable = false;
+  atlasSearchBusy = false;
+  if (atlasSearchInput) atlasSearchInput.value = "";
+  if (dashboardData) renderDashboard(dashboardData);
+}
+
+function atlasSearchStatusCopy() {
+  if (!atlasSearchQuery) return dashboardData ? atlasProvenanceCopy(dashboardData) : "";
+  if (atlasSearchBusy) return "Searching.";
+  if (atlasSearchUnavailable) return "Search unavailable.";
+  if (!atlasSearchResults.length) return `No matches for "${atlasSearchQuery}".`;
+  return `${atlasSearchResults.length} matches for "${atlasSearchQuery}".`;
+}
+
+function renderAtlasSearch() {
+  if (!atlasSearchSectionEl || !atlasSearchResultsEl || !atlasSearchSummaryEl) return;
+  const active = Boolean(atlasSearchQuery);
+  atlasSearchSectionEl.hidden = !active;
+  if (atlasSearchClearButton) atlasSearchClearButton.hidden = !active;
+  if (!active) {
+    atlasSearchResultsEl.innerHTML = "";
+    atlasSearchSummaryEl.textContent = "";
+    return;
+  }
+  atlasSearchSummaryEl.textContent = atlasSearchStatusCopy();
+  atlasSearchResultsEl.innerHTML = "";
+  if (atlasSearchUnavailable || !atlasSearchResults.length) return;
+  for (const result of atlasSearchResults.slice(0, 8)) {
+    atlasSearchResultsEl.append(atlasSearchResultButton(result));
+  }
+}
+
+function atlasSearchResultButton(result) {
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = `atlas-search-result ${result.project_id === selectedProjectId ? "active" : ""}`;
+  const title = result.title || result.project?.title || result.project_id || "Untitled project";
+  const terms = (result.matched_terms || []).slice(0, 4).join(", ");
+  const snippet = (result.snippets || [])[0];
+  const width = Math.max(8, Math.min(100, Number(result.score || 0) * 100)).toFixed(0);
+  button.innerHTML = `
+    <strong>${escapeHtml(title)}</strong>
+    <span class="atlas-search-meta">${escapeHtml(terms || "Related project")}</span>
+    <span class="atlas-search-score" aria-hidden="true"><i style="width: ${width}%"></i></span>
+    ${
+      snippet
+        ? `<span class="atlas-search-snippet">${escapeHtml(snippet.source)}: ${escapeHtml(snippet.text)}</span>`
+        : ""
+    }
+  `;
+  button.addEventListener("click", () => {
+    selectedProjectId = result.project_id || selectedProjectId;
+    if (dashboardData) renderDashboard(dashboardData);
+  });
+  return button;
+}
+
 function renderDashboard(data) {
   if (!data?.points?.length) {
     handleDashboardError(new Error("empty dashboard payload"));
@@ -334,7 +472,8 @@ function renderDashboard(data) {
   renderAtlasSvg(data);
   renderAtlasDetail(currentAtlasPoint(data));
   renderAtlasReport(data);
-  if (atlasStatusEl) atlasStatusEl.textContent = atlasProvenanceCopy(data);
+  renderAtlasSearch();
+  if (atlasStatusEl) atlasStatusEl.textContent = atlasSearchQuery ? atlasSearchStatusCopy() : atlasProvenanceCopy(data);
 }
 
 function atlasProvenanceCopy(data) {
@@ -445,6 +584,16 @@ function renderAtlasSvg(data) {
     atlasSvgEl.append(line);
   }
 
+  for (const point of data.points || []) {
+    if (!atlasSearchResultIds.has(point.id)) continue;
+    const ring = svgEl("circle");
+    ring.setAttribute("cx", point.x);
+    ring.setAttribute("cy", point.y);
+    ring.setAttribute("r", (atlasPointRadiusNumber(point) + 0.62).toFixed(3));
+    ring.setAttribute("class", `atlas-search-ring ${visible.has(point.id) ? "" : "dim"}`);
+    atlasSvgEl.append(ring);
+  }
+
   for (const point of data.points || []) {
     const circle = svgEl("circle");
     circle.setAttribute("cx", point.x);
@@ -453,7 +602,9 @@ function renderAtlasSvg(data) {
     circle.setAttribute("fill", atlasColor(clusterIndex.get(point.cluster_id) || 0));
     circle.setAttribute(
       "class",
-      `atlas-dot ${visible.has(point.id) ? "" : "dim"} ${point.id === selectedProjectId ? "selected" : ""}`,
+      `atlas-dot ${visible.has(point.id) ? "" : "dim"} ${point.id === selectedProjectId ? "selected" : ""} ${
+        atlasSearchResultIds.has(point.id) ? "search-match" : ""
+      }`,
     );
     circle.setAttribute("tabindex", "0");
     circle.setAttribute("role", "button");
@@ -482,11 +633,21 @@ function visibleAtlasPoints(data) {
   return (data.points || []).filter((point) => {
     const clusterMatch = !selectedClusterId || point.cluster_id === selectedClusterId;
     const questMatch = !selectedQuestId || (point.quest_ids || []).includes(selectedQuestId);
-    return clusterMatch && questMatch;
+    const searchMatch = !atlasSearchQuery || atlasSearchResultIds.has(point.id);
+    return clusterMatch && questMatch && searchMatch;
   });
 }
 
 function labelAtlasPoints(data) {
+  if (atlasSearchQuery && atlasSearchResults.length) {
+    const pointsById = new Map((data.points || []).map((point) => [point.id, point]));
+    const visibleIds = new Set(visibleAtlasPoints(data).map((point) => point.id));
+    return atlasSearchResults
+      .map((result) => pointsById.get(result.project_id))
+      .filter(Boolean)
+      .filter((point) => visibleIds.has(point.id))
+      .slice(0, 16);
+  }
   const visible = visibleAtlasPoints(data);
   return [...visible].sort((left, right) => Number(right.likes || 0) - Number(left.likes || 0)).slice(0, 12);
 }
@@ -585,7 +746,11 @@ function atlasQuestLabel(questId) {
 }
 
 function atlasPointRadius(point) {
-  return (0.62 + Math.min(0.72, Math.sqrt(Number(point.likes || 0)) * 0.12)).toFixed(3);
+  return atlasPointRadiusNumber(point).toFixed(3);
+}
+
+function atlasPointRadiusNumber(point) {
+  return 0.62 + Math.min(0.72, Math.sqrt(Number(point.likes || 0)) * 0.12);
 }
 
 function atlasShortTitle(title) {

static/index.html

@@ -33,6 +33,13 @@
         <path d="M4 5v5h5" />
         <path d="M5.5 14a7 7 0 1 0 1.2-6.7L4 10" />
       </symbol>
+      <symbol id="icon-search" viewBox="0 0 24 24">
+        <circle cx="11" cy="11" r="6" />
+        <path d="M16 16l4 4" />
+      </symbol>
+      <symbol id="icon-x" viewBox="0 0 24 24">
+        <path d="M6 6l12 12M18 6L6 18" />
+      </symbol>
       <symbol id="icon-check" viewBox="0 0 24 24">
         <path d="M5 12l4 4 10-11" />
       </symbol>
@@ -49,10 +56,24 @@
     <main id="atlas-view" class="atlas-shell" aria-label="Live project atlas">
       <section class="atlas-stage">
         <header class="atlas-topbar">
-          <div>
+          <div class="atlas-title-block">
             <p class="atlas-kicker">Live project atlas</p>
             <h1>Idea Map</h1>
           </div>
+          <form id="atlas-search-form" class="atlas-search" role="search">
+            <label class="sr-only" for="atlas-search">Search the project atlas</label>
+            <svg class="icon" aria-hidden="true"><use href="#icon-search"></use></svg>
+            <input
+              id="atlas-search"
+              type="search"
+              autocomplete="off"
+              spellcheck="false"
+              placeholder="Search projects, ideas, quests..."
+            />
+            <button id="atlas-search-clear" class="atlas-search-clear" type="button" title="Clear search" hidden>
+              <svg class="icon" aria-hidden="true"><use href="#icon-x"></use></svg>
+            </button>
+          </form>
           <div class="atlas-actions">
             <span id="atlas-status" class="atlas-status" aria-live="polite">Loading atlas.</span>
             <button id="refresh-dashboard" class="btn btn-ghost" type="button" title="Refresh the project atlas">
@@ -69,6 +90,11 @@
         <section class="atlas-layout">
           <aside class="atlas-panel atlas-left" aria-label="Atlas filters">
             <div class="atlas-stat-grid" id="atlas-stats"></div>
+            <section id="atlas-search-section" class="atlas-section atlas-search-section" hidden>
+              <div class="eyebrow">Best matches</div>
+              <p id="atlas-search-summary" class="atlas-search-summary"></p>
+              <div id="atlas-search-results" class="atlas-list"></div>
+            </section>
             <section class="atlas-section">
               <div class="eyebrow">Clusters</div>
               <div id="atlas-clusters" class="atlas-list"></div>

static/styles.css

@@ -26,6 +26,10 @@
   box-sizing: border-box;
 }
 
+[hidden] {
+  display: none !important;
+}
+
 html,
 body {
   min-height: 100%;
@@ -152,14 +156,18 @@ textarea:disabled {
 }
 
 .atlas-topbar {
-  display: flex;
+  display: grid;
+  grid-template-columns: minmax(155px, auto) minmax(260px, 540px) minmax(300px, 1fr);
   align-items: flex-end;
-  justify-content: space-between;
   gap: 20px;
   padding: 30px 42px 18px;
   border-bottom: 1px solid var(--rule);
 }
 
+.atlas-title-block {
+  min-width: 0;
+}
+
 .atlas-kicker {
   margin: 0 0 7px;
   color: var(--ink-faint);
@@ -181,6 +189,68 @@ textarea:disabled {
   letter-spacing: 0;
 }
 
+.atlas-search {
+  display: flex;
+  min-width: 0;
+  align-items: center;
+  gap: 9px;
+  height: 42px;
+  padding: 0 12px;
+  color: var(--ink-soft);
+  background: rgba(255, 247, 224, 0.4);
+  border: 1px solid var(--rule);
+  border-radius: 8px;
+  box-shadow: inset 0 1px 0 rgba(255, 247, 224, 0.42);
+}
+
+.atlas-search:focus-within {
+  border-color: rgba(154, 43, 34, 0.48);
+  box-shadow:
+    inset 0 1px 0 rgba(255, 247, 224, 0.42),
+    0 0 0 3px rgba(176, 125, 18, 0.12);
+}
+
+.atlas-search input {
+  min-width: 0;
+  width: 100%;
+  height: 100%;
+  padding: 0;
+  color: var(--ink);
+  background: transparent;
+  border: 0;
+  outline: 0;
+  font-family: var(--label);
+  font-size: 0.86rem;
+  font-weight: 760;
+}
+
+.atlas-search input::placeholder {
+  color: var(--ink-faint);
+  opacity: 0.82;
+}
+
+.atlas-search input::-webkit-search-cancel-button {
+  display: none;
+}
+
+.atlas-search-clear {
+  display: inline-grid;
+  width: 26px;
+  height: 26px;
+  flex: 0 0 auto;
+  place-items: center;
+  padding: 0;
+  color: var(--ink-faint);
+  background: transparent;
+  border: 0;
+  border-radius: 50%;
+}
+
+.atlas-search-clear:hover {
+  color: var(--ink);
+  background: rgba(73, 49, 22, 0.08);
+}
+
 .atlas-actions {
   display: flex;
   flex-wrap: wrap;
@@ -200,6 +270,70 @@ textarea:disabled {
   text-align: right;
 }
 
+.atlas-search-summary {
+  margin: 0 0 9px;
+  color: var(--ink-faint);
+  font-family: var(--label);
+  font-size: 0.72rem;
+  font-weight: 760;
+  line-height: 1.4;
+}
+
+.atlas-search-result {
+  display: grid;
+  width: 100%;
+  gap: 6px;
+  padding: 10px 11px;
+  color: var(--ink);
+  background: rgba(255, 247, 224, 0.38);
+  border: 1px solid var(--rule-soft);
+  border-left: 3px solid var(--leaf);
+  border-radius: 7px;
+  text-align: left;
+}
+
+.atlas-search-result:hover,
+.atlas-search-result.active {
+  background: rgba(47, 107, 65, 0.1);
+  border-color: rgba(47, 107, 65, 0.35);
+}
+
+.atlas-search-result.active {
+  border-left-color: var(--oxblood);
+}
+
+.atlas-search-result strong {
+  color: var(--ink);
+  font-family: var(--serif);
+  font-size: 0.88rem;
+  line-height: 1.2;
+}
+
+.atlas-search-meta,
+.atlas-search-snippet {
+  color: var(--ink-faint);
+  font-family: var(--label);
+  font-size: 0.68rem;
+  font-weight: 760;
+  line-height: 1.35;
+}
+
+.atlas-search-score {
+  display: block;
+  height: 5px;
+  overflow: hidden;
+  background: rgba(73, 49, 22, 0.14);
+  border-radius: 999px;
+}
+
+.atlas-search-score i {
+  display: block;
+  width: 0;
+  height: 100%;
+  background: linear-gradient(90deg, var(--leaf) 0%, var(--gold) 72%, var(--oxblood) 100%);
+  border-radius: inherit;
+}
+
 .atlas-layout {
   display: grid;
   grid-template-columns: 300px minmax(0, 1fr) 330px;
@@ -349,8 +483,22 @@ textarea:disabled {
   stroke-width: 0.42;
 }
 
+.atlas-dot.search-match {
+  opacity: 1;
+  stroke: #fff0b5;
+  stroke-width: 0.45;
+}
+
+.atlas-search-ring {
+  pointer-events: none;
+  fill: none;
+  stroke: rgba(176, 125, 18, 0.55);
+  stroke-width: 0.35;
+}
+
 .atlas-dot.dim,
-.atlas-link.dim {
+.atlas-link.dim,
+.atlas-search-ring.dim {
   opacity: 0.08;
 }
 
@@ -1472,6 +1620,14 @@ textarea:disabled {
 }
 
 @media (max-width: 1080px) {
+  .atlas-topbar {
+    grid-template-columns: 1fr minmax(260px, 1.2fr);
+  }
+
+  .atlas-actions {
+    grid-column: 1 / -1;
+  }
+
   .atlas-layout {
     grid-template-columns: 260px minmax(0, 1fr);
   }
@@ -1519,7 +1675,7 @@ textarea:disabled {
 
   .atlas-topbar {
     align-items: flex-start;
-    flex-direction: column;
+    grid-template-columns: 1fr;
     padding: 18px;
   }
 
@@ -1532,6 +1688,10 @@ textarea:disabled {
     width: 100%;
   }
 
+  .atlas-search {
+    width: 100%;
+  }
+
   .atlas-status {
     min-width: 100%;
     text-align: left;

tests/test_app.py

@@ -12,6 +12,7 @@ from app import (
     chapter_api,
     chapter_artifact,
     dashboard,
+    dashboard_search,
     dashboard_refresh_start,
     dashboard_refresh_status,
     demo_bundle,
@@ -143,6 +144,29 @@ def test_dashboard_endpoint_exposes_atlas_payload() -> None:
     )
 
 
+def test_dashboard_search_endpoint_returns_bm25_matches() -> None:
+    payload = dashboard_search(q="surgical anatomy", limit=5)
+
+    assert payload["algorithm"] == "bm25-text-v1"
+    assert payload["query"] == "surgical anatomy"
+    assert payload["results"]
+    assert (
+        payload["results"][0]["project_id"]
+        == "build-small-hackathon/surgical-tissue-segmentation"
+    )
+    assert payload["results"][0]["point"]["id"] == payload["results"][0]["project_id"]
+    assert payload["results"][0]["snippets"]
+
+
+def test_dashboard_search_endpoint_rejects_empty_query() -> None:
+    try:
+        dashboard_search(q="   ")
+    except Exception as error:
+        assert getattr(error, "status_code", None) == 400
+    else:
+        raise AssertionError("dashboard search should reject an empty query")
+
+
 def test_refresh_error_format_includes_exception_chain() -> None:
     try:
         try:

tests/test_dashboard_search.py

@@ -0,0 +1,65 @@
+from hackathon_advisor.dashboard import build_dashboard_payload
+from hackathon_advisor.data import Project, ProjectIndex, build_index_payload
+from hackathon_advisor.dashboard_search import DashboardSearchIndex
+
+
+def test_dashboard_search_bm25_ranks_text_matches() -> None:
+    project_index = fake_project_index()
+    payload = build_dashboard_payload(project_index, generated_at="2026-06-08T00:00:00+00:00")
+    search_index = DashboardSearchIndex(project_index.projects, payload)
+
+    result = search_index.search("project 4 summary", limit=3)
+
+    assert result["algorithm"] == "bm25-text-v1"
+    assert result["results"]
+    assert result["results"][0]["project_id"] == "build-small-hackathon/project-4"
+    assert result["results"][0]["score"] == 1.0
+    assert result["results"][0]["snippets"]
+
+
+def test_dashboard_search_splits_slug_tokens() -> None:
+    project_index = fake_project_index()
+    payload = build_dashboard_payload(project_index, generated_at="2026-06-08T00:00:00+00:00")
+    search_index = DashboardSearchIndex(project_index.projects, payload)
+
+    result = search_index.search("project-7", limit=3)
+
+    assert result["results"][0]["project_id"] == "build-small-hackathon/project-7"
+    assert "project-7" in result["results"][0]["matched_terms"]
+
+
+def fake_project_index() -> ProjectIndex:
+    projects = [
+        Project(
+            id=f"build-small-hackathon/project-{index}",
+            title=f"Project {index}",
+            summary=f"Offline project planner {index}",
+            tags=("gradio", "local-first"),
+            models=("tiny-model",),
+            datasets=(),
+            likes=index,
+            sdk="gradio",
+            license="mit",
+            created_at="2026-06-01T00:00:00+00:00",
+            last_modified=f"2026-06-{index + 1:02d}T00:00:00+00:00",
+            host=f"https://project-{index}.hf.space",
+            url=f"https://huggingface.co/spaces/build-small-hackathon/project-{index}",
+            app_file="app.py",
+            app_file_embedding_text=f"local inference gradio small model artifact project {index}",
+            readme_body=f"README evidence for project {index}",
+        )
+        for index in range(10)
+    ]
+    embeddings = []
+    for index in range(10):
+        vector = [0.0] * 10
+        vector[index] = 1.0
+        embeddings.append(vector)
+    generated_at = "2026-06-08T00:00:00+00:00"
+    source = "https://example.test/spaces"
+    return ProjectIndex(
+        projects=projects,
+        generated_at=generated_at,
+        source=source,
+        index_payload=build_index_payload(projects, generated_at, source, embeddings),
+    )

tests/test_frontend_copy.py

@@ -9,8 +9,11 @@ def test_main_interface_copy_is_builder_facing() -> None:
     assert "Live project atlas" in html
     assert "Refresh map" in html
     assert "Open advisor" in html
+    assert 'id="atlas-search"' in html
+    assert "Search projects, ideas, quests..." in html
     assert 'id="advisor-view"' in html
     assert "/api/dashboard" in app_js
+    assert "/api/dashboard/search" in app_js
     assert "/api/dashboard/refresh" in app_js
     assert "renderAtlasSvg" in app_js
     assert "Directions to test" in html
@@ -37,6 +40,13 @@ def test_main_interface_copy_is_builder_facing() -> None:
     assert "Voice note" in html
     assert "ideaCardAriaLabel" in app_js
     assert "Select idea:" in app_js
+    assert "Hybrid" not in combined
+    assert "Keyword" not in combined
+    assert "Semantic" not in combined
+    assert "Refresh failed:" not in app_js
+    assert "Refresh could not start: ${error.message}" not in app_js
+    assert "Refresh status unavailable: ${error.message}" not in app_js
+    assert "atlasRefreshProgressEl.textContent = error.message" not in app_js
 
     stale_jargon = [
         "No wax path pressed.",