Refine unified search answer shaping and viability

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

@@ -122,6 +122,7 @@ sequenceDiagram
 `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.
+- `contextAnswer` is query-driven rather than mode-driven: compare-like requests may blend close evidence clusters, while scoped troubleshoot requests prefer a single decisive answer when one result clearly leads.
 - `overflow` is additive and bounded so FE can show "outside the current page, but likely relevant" results without reintroducing a scope toggle.
 - `overflow` is intentionally narrow: it is suppressed when the current-scope winner has a clear lead, so FE can trust the primary section as the best local answer.
 - `coverage` is additive and bounded so FE can suppress misleading suggestions when the active corpus has no sensible candidates for that domain.
@@ -132,6 +133,10 @@ sequenceDiagram
 `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.
+- Additive fields:
+  - `viabilityState`: `grounded` | `needs_clarification` | `no_match` | `scope_unready` | `corpus_unready`
+  - `scopeReady`: `true` when the current route scope has indexed corpus behind it
+- `viable=true` is reserved for suggestions that already have grounded evidence; clarify-only suggestions are not considered executable.
 - Does not require telemetry and does not record answer-frame analytics.
 
 OpenAPI contract presence is validated by integration test: