context detemrinistic + randomized searches and fix for setup from stella-ops.local rather 127.1.0.*

docs/modules/ui/search-chip-context-contract.md

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