# 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

## Priority rollout ownership
| Context ID | Route family | Page ownership rule | Verification floor |
| --- | --- | --- | --- |
| `findings` | `/security/triage`, `/security/findings` | Security triage pages own the findings questions and clarifiers. | Mocked Playwright journey + shared search regressions |
| `policy` | `/ops/policy` | Policy workspace owns the questions and recovery prompts for rules, gates, and exceptions. | Mocked Playwright journey + shared search regressions |
| `doctor` | `/ops/operations/doctor`, `/ops/operations/system-health` | Doctor pages own the health-check questions and release-readiness follow-ups. | Mocked Playwright journey + live Doctor route pack |
| `timeline` | `/ops/timeline`, `/audit`, `/evidence/audit-log` | Timeline/Audit pages own time-window clarifiers and causal follow-ups. | Mocked Playwright journey |
| `releases` | `/releases`, `/mission-control` | Release-control pages own approval/blocker/next-step questions. | Mocked Playwright journey |

## Page team checklist
1. Add or update the route entry in `SEARCH_CONTEXT_DEFINITIONS`.
2. Define bounded `commonQuestions[]` and `clarifyingQuestions[]`.
3. Keep copy operator-facing; do not expose Stella internals or scoring jargon.
4. Verify the page still works with telemetry disabled or OTLP unset.
5. Add/update unit coverage for route-specific questions and a Playwright journey for the page family.

## 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 guidance 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[]` as non-executable narrowing guidance 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.

## Optional telemetry hooks
- Search may emit optional client-side telemetry markers for backlog triage:
  - `search_self_serve_gap`
  - `search_self_serve_reformulation`
  - `search_self_serve_recovery`
  - `search_self_serve_suggestion_suppressed`
- These markers are additive only. If telemetry is disabled or the sink is unavailable, search behavior, history, and assistant handoffs must remain unchanged.
- Marker payloads must avoid raw query text. Use route, answer state, counts, and reformulation depth instead.

## Gap review workflow
1. Review repeated `search_self_serve_gap` and `search_self_serve_reformulation` events by route family.
2. Compare them with visible no-result/clarify journeys from Playwright and operator feedback.
3. Update the page-owned question set or starter chips for the affected route.
4. Add or tighten a Playwright journey before marking the gap closed.
5. Record the adjustment in the active sprint `Execution Log` so the change is traceable.

## 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 guidance rendering
   - answer-to-AdvisoryAI handoff
   - priority-route rollout journeys (`findings`, `policy`, `doctor`, `timeline`, `releases`)
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.