Add implicit scope weighting and suggestion viability

docs/modules/advisory-ai/knowledge-search.md

@@ -143,6 +143,7 @@ Implemented in `src/AdvisoryAI/StellaOps.AdvisoryAI/KnowledgeSearch/KnowledgeSea
   - Unified search emits hashed query telemetry (`SHA-256` query hash, intent, domain weights, latency, top domains) via `IUnifiedSearchTelemetrySink`.
   - Search analytics persistence stores hashed query keys (`SHA-256`, normalized) and pseudonymous user keys (tenant+user hash) in analytics/feedback artifacts.
   - Self-serve analytics is optional and privacy-preserving: when clients emit `answer_frame`, `reformulation`, or `rescue_action`, persistence stores a tenant-scoped hashed session id plus bounded answer metadata (`answer_status`, `answer_code`) instead of raw prompt history.
+  - New ranking behavior does not depend on telemetry. Implicit scope weighting, overflow surfacing, answer blending, and suggestion viability all work when analytics sinks are disabled or no client analytics events are emitted.
   - Quality metrics surface self-serve gaps as `fallbackAnswerRate`, `clarifyRate`, `insufficientRate`, `reformulationCount`, `rescueActionCount`, and `abandonedFallbackCount`; alerting adds `fallback_loop` and `abandoned_fallback` signals for backlog review.
   - Free-form feedback comments are redacted at persistence time to avoid storing potential PII in analytics tables.
   - Server-side search history remains user-facing functionality (raw query for history UX) and is keyed by pseudonymous user hash.
@@ -194,9 +195,33 @@ AKS commands:
 - `stella advisoryai sources prepare [--repo-root ...] [--docs-allowlist ...] [--docs-manifest-output ...] [--openapi-output ...] [--doctor-seed ...] [--doctor-controls-output ...] [--overwrite] [--json]`
 - Unified-search API operations:
   - `POST /v1/search/query`
+  - `POST /v1/search/suggestions/evaluate`
   - `POST /v1/search/synthesize`
   - `POST /v1/search/index/rebuild`
 
+`POST /v1/search/query` additive response fields:
+- `overflow`: bounded related results that fell outside the current ambient page scope but remain materially relevant.
+- `coverage`: bounded domain coverage diagnostics so FE can suppress suggestions or chips when the active corpus is empty for that suggestion.
+
+`POST /v1/search/suggestions/evaluate`:
+- Accepts a bounded query set plus optional filters/ambient context.
+- Returns per-query viability, matched domain, candidate count, and the same bounded coverage view used by the main query response.
+- Intended for FE-owned suggestion chips and other proactive prompts so the UI does not advertise dead searches.
+
+Example:
+```bash
+curl -X POST http://127.0.0.1:10451/v1/search/suggestions/evaluate \
+  -H "Content-Type: application/json" \
+  -H "X-StellaOps-Tenant: test-tenant" \
+  -H "Authorization: Bearer <token-with-advisory-ai:operate>" \
+  -d '{
+    "queries": ["database connectivity", "oidc readiness"],
+    "ambient": {
+      "currentRoute": "/ops/operations/doctor"
+    }
+  }'
+```
+
 Notes:
 - Do not assume `stella` is already installed on `PATH` in a source checkout. Build or run it from source as described in `docs/API_CLI_REFERENCE.md` and `docs/modules/cli/guides/quickstart.md`.
 - `stella advisoryai sources prepare` needs `STELLAOPS_BACKEND_URL` (or equivalent CLI config) when live Doctor check discovery is expected. Without that URL, use the checked-in Doctor seed/control files and the HTTP rebuild endpoints for local verification.
@@ -378,6 +403,7 @@ Current live verification coverage:
 - Rebuild order exercised against a running local service: `POST /v1/advisory-ai/index/rebuild` then `POST /v1/search/index/rebuild`
 - Verified live query: `database connectivity`
 - Verified live outcome: response includes `contextAnswer.status = grounded`, citations, and entity cards over ingested data
+- Verified live suggestion lane: the Doctor-page `database connectivity` chip remains a viable query after rebuild and is exercised by `src/Web/StellaOps.Web/tests/e2e/unified-search-contextual-suggestions.live.e2e.spec.ts`
 - Other routes still rely on deterministic mock-backed Playwright coverage until their ingestion parity is explicitly verified
 
 Or use the full CI testing stack:

docs/modules/advisory-ai/unified-search-architecture.md

@@ -47,6 +47,7 @@ flowchart LR
   - Ambient/session carry-forward
   - Graph gravity
   - Optional popularity and freshness controls
+- Current-page scope is applied here as a ranking bias, not a hard filter. When outside-scope results remain materially stronger, the response surfaces them in bounded `overflow` metadata instead of hiding them.
 - `EntityCardAssembler` groups facets into entity cards and resolves aliases.
 
 ### Layer 4: Synthesis
@@ -113,16 +114,24 @@ sequenceDiagram
 
 ## Contracts and API Surface
 - `POST /v1/search/query`
+- `POST /v1/search/suggestions/evaluate`
 - `POST /v1/search/synthesize`
 - `POST /v1/search/index/rebuild`
 
 `POST /v1/search/query` response notes:
 - Entity cards remain the primary retrieval payload.
 - `contextAnswer` is the preferred answer-first surface for Web self-serve UX when present.
+- `overflow` is additive and bounded so FE can show "outside the current page, but likely relevant" results without reintroducing a scope toggle.
+- `coverage` is additive and bounded so FE can suppress misleading suggestions when the active corpus has no sensible candidates for that domain.
 - Live local verification currently covers the Doctor/knowledge path after the documented rebuild order:
   1. `POST /v1/advisory-ai/index/rebuild`
   2. `POST /v1/search/index/rebuild`
 
+`POST /v1/search/suggestions/evaluate` response notes:
+- Intended for proactive suggestion chips and page-owned prompts before the user commits a search.
+- Returns per-query viability plus bounded domain coverage.
+- Does not require telemetry and does not record answer-frame analytics.
+
 OpenAPI contract presence is validated by integration test:
 - `UnifiedSearchEndpointsIntegrationTests.OpenApi_Includes_UnifiedSearch_Contracts`