# 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`)
- 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".
- A recent-action question may be prepended from the latest meaningful page action:
  - opened/used result -> why-it-matters question
  - search/chat expansion -> what-to-verify-next question
  - fallback -> related follow-up question
- Result-state answer panels use:
  - `commonQuestions[]` as follow-up questions when grounded evidence exists
  - `clarifyingQuestions[]` when no grounded answer exists
- "Related searches" 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.