# Search Chip Context Contract

## Purpose
- Define one deterministic contract for page-aware search chips.
- Let feature teams add page suggestions without editing `AmbientContextService` logic.
- Blend route context, last few page actions, and bounded suggestion randomization.

## Rule (mandatory for page teams)
- Every page that needs custom search chips must declare a context entry in `SEARCH_CONTEXT_DEFINITIONS`.
- Page components should implement `SearchContextComponent` with `searchContextId` so ownership is explicit.
- Context definitions must provide:
  - `id`
  - `routePrefixes`
  - optional `domain`
  - optional `searchSuggestions[]`
  - optional `chatSuggestions[]`
  - optional `chatRoutePattern`
- Suggestion arrays must stay deterministic and bounded:
  - at most 3 base chips per page context
  - short, action-oriented text
  - no tenant/user secrets in fallback text

## Source of truth
- Contract and registry:
  - `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`

## Runtime behavior
- Base chips come from the page context array.
- A deterministic rotation (session + route scope + 5-minute bucket) varies chip order.
- Last few actions for the current page scope are tracked (bounded history, TTL 15 minutes).
- Up to 2 `follow up: ...` chips are generated from recent actions and prioritized above base chips.
- One strategic chip is generated from dominant/recent action intent.

## Page ownership workflow
1. Add/adjust a context in `SEARCH_CONTEXT_DEFINITIONS`.
2. Ensure page component exposes the same `searchContextId` (implements `SearchContextComponent`).
3. Add/adjust unit tests in `ambient-context.service.spec.ts`.
4. Add/adjust Playwright tests for route chips + action-driven chips.

## Non-goals
- No unbounded per-page suggestion memory.
- No runtime remote fetch for chip definitions.
- No randomization based on `Math.random()` (must remain replayable).