Add answer-first self-serve search UX

docs/modules/ui/search-self-serve-contract.md

@@ -0,0 +1,65 @@
+# 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.