git.stella-ops.org/docs/modules/ui/search-zero-learning-primary-entry.md

Search Zero-Learning Primary Entry

Why this exists

• Search must be the default entry into Stella Ops for users who do not know Stella terminology, domain boundaries, or internal product structure.
• The current model asks the user to understand too many concepts before they can succeed: Find/Explain/Act, explicit scope switching, recovery actions, and a separate AdvisoryAI destination.
• Live verification also shows a real reliability gap: suggestion chips can render even when the active corpus cannot answer them. On 2026-03-07, the running AdvisoryAI service at http://127.1.0.44 rebuilt with documentCount=0, chunkCount=0, and doctorProjectionCount=0, while unified overlays rebuilt with only chunkCount=14. Querying database connectivity then returned zero cards. The current UX still offered that suggestion.

Product rules

1. Search is the primary entry point.
2. AdvisoryAI is a secondary deep-dive opened from search, not a competing starting point.
3. Search should infer relevance and intent; the user should not need to choose a mode.
4. Search should bias to the current page context automatically; the user should not need to toggle scope.
5. Search should never advertise a suggestion that cannot execute against the active corpus.
6. Search history should contain only successful searches.
7. Telemetry remains optional. Search behavior must not depend on analytics emission.

Target interaction model

Entry

• Keep one primary search field in the top bar.
• Add a compact AdvisoryAI launcher icon beside the search input.
• Opening chat from that icon inherits the current page, current query, and top evidence when available.

Query understanding

• Infer likely user intent from the query and visible page context.
• Weight current page/domain first.
• If current-scope evidence is weak, show overflow results from outside the page scope below the in-scope section instead of asking the user to broaden scope manually.

Result presentation

• Place Did you mean directly below the input because it is an input correction, not a result refinement.
• Remove explicit Find / Explain / Act controls.
• Remove the explicit scope toggle chip.
• Remove manual result-domain refinements from the primary flow; the server should rank the current page first and render any cross-scope overflow as a secondary section instead.
• Remove the recovery panel.
• If top results are close in score, compose one short summary across them.
• If one result is clearly dominant, present that answer first and then cards.

Suggestions

• Page suggestions become executable search intents, not static chips.
• A suggestion is only shown if:
  • its preferred domain has live evidence, or
  • the backend confirms non-zero candidate coverage for it.
• If the current corpus is empty for that page/domain, suppress those suggestion chips instead of showing dead leads.

History

• Persist and render only searches that returned results.
• Keep history clear as a low-emphasis icon action, not a labeled call-to-action.

Runtime rules

Implicit scope weighting

• Current route/domain is a ranking boost, not a hard filter.
• Visible entity keys and last action increase local relevance.
• Out-of-scope results are still allowed, but only after in-scope candidates are exhausted or materially weaker.

Answer blending

• If top-N cards fall within a narrow score band, emit a blended summary with citations from multiple cards.
• If score separation is strong, emit a single-result grounded answer.
• The frontend should not ask the user to choose whether they want find or explain; the backend should infer the dominant answer shape.

Suggestion viability

• Suggestions must be validated against the current corpus before rendering.
• Knowledge/domain emptiness should be detectable so the UI can suppress invalid chips.
• Empty-state contextual chips and page-owned common-question chips should preflight through the backend viability endpoint before they render.
• Live Playwright coverage must assert that every surfaced suggestion returns visible results.

Phase map

• Phase 1: FE primary-entry consolidation and removal of explicit search controls.
• Phase 2: AdvisoryAI implicit scope weighting, answer blending, and suggestion viability.
• Phase 3: FE consumption of overflow results and executable suggestion contracts.
  • Implemented on 2026-03-07: backend contextAnswer is now preferred over frontend heuristics, overflow renders as a secondary result section, and suggestion viability preflight suppresses dead chips before they are shown.
• Phase 4: Live Playwright reliability matrix with corpus preflight and chip-success guarantees.