git.stella-ops.org/docs/modules/ui/search-self-serve-contract.md

Search Self-Serve Contract

Purpose

• Define the page-owned contract for answer-first search.
• Ensure every high-value page can expose common operator questions and clarifying prompts without editing GlobalSearchComponent.
• Keep the self-serve experience deterministic, evidence-first, and testable.

Rule (mandatory for page teams)

• Every page that wants answer-first self-serve behavior must declare selfServe metadata in SEARCH_CONTEXT_DEFINITIONS.
• Page components should continue to implement SearchContextComponent so ownership remains explicit.
• selfServe definitions must provide one or both of:
  • commonQuestions[]
  • clarifyingQuestions[]
• Question entries must provide:
  • key / fallback for the executable question text
  • optional kind (page, clarify, recent)
  • optional preferredModes (find, explain, act)
• Question arrays must stay deterministic and bounded:
  • at most 3 base common questions per page
  • at most 2 base clarifying questions per page
  • concise, operator-facing wording
  • no tenant secrets or volatile IDs in fallback copy

Answer-first UX contract

• Every non-empty search must render one visible answer state before raw results:
  • grounded
  • clarify
  • insufficient
• grounded states must expose visible evidence summary plus citations or top-result references.
• clarify states must offer narrowing questions instead of a blank panel.
• insufficient states must explain the lack of grounding and still provide credible next questions or next searches.

Runtime behavior

• Empty-state search uses commonQuestions[] for page-owned "Common questions".
• The active mode (Find, Explain, Act) reorders questions via preferredModes.
• A recent-action question may be prepended from the latest meaningful page action:
  • Find -> related discovery question
  • Explain -> why-it-matters question
  • Act -> what-to-do-next question
• Result-state answer panels use:
  • commonQuestions[] as follow-up questions when grounded evidence exists
  • clarifyingQuestions[] when no grounded answer exists
• "Search next" remains driven by contextual chip logic so pages do not need to define a second parallel action system.

Source of truth

• Page registry and interfaces:
  • src/Web/StellaOps.Web/src/app/core/services/search-context.registry.ts
• Runtime composition:
  • src/Web/StellaOps.Web/src/app/core/services/ambient-context.service.ts
• Search surface:
  • src/Web/StellaOps.Web/src/app/layout/global-search/global-search.component.ts

Testing requirements

1. Add unit coverage for route-specific questions in ambient-context.service.spec.ts.
2. Add unit coverage for answer-state rendering in global-search.component.spec.ts.
3. Add Playwright coverage for:
   • grounded answer
   • clarify recovery
   • answer-to-AdvisoryAI handoff
4. Keep route and API behavior mocked/deterministic; no live network dependencies.

Relationship to chip contract

• search-chip-context-contract.md still governs contextual chips and route-suggestion behavior.
• This document governs answer-first questions and fallback states.
• Page teams adding self-serve behavior usually need to update both contracts together.