Improve search and advisory UX flows

docs/implplan/SPRINT_20260306_002_FE_search_advisory_quality_ux.md

@@ -0,0 +1,136 @@
+# Sprint 20260306-002 - Search and Advisory Quality UX
+
+## Topic & Scope
+- Upgrade global search and AdvisoryAI UX from "smart suggestions" to "explainable operator guidance" with visible context, rationale, and next-step framing.
+- Make contextual search state legible: current page, active domain, and latest meaningful action should be visible in the search surface.
+- Improve suggestion quality UX with richer chips that explain why they are being suggested and what type of action they represent.
+- Working directory: `src/Web/StellaOps.Web`.
+- Expected evidence: Angular unit tests, Playwright behavioral tests, updated UI docs, and sprint execution log entries.
+
+## Dependencies & Concurrency
+- Depends on `docs/implplan/SPRINT_20260306_001_Web_contextual_search_suggestions.md` for ambient context capture and chip registry groundwork.
+- Upstream implementation points:
+  - `src/Web/StellaOps.Web/src/app/layout/global-search/global-search.component.ts`
+  - `src/Web/StellaOps.Web/src/app/core/services/ambient-context.service.ts`
+  - `src/Web/StellaOps.Web/src/app/core/services/search-context.registry.ts`
+  - `src/Web/StellaOps.Web/src/app/features/advisory-ai/chat/chat-message.component.ts`
+- Safe parallelism:
+  - UI presentation work can run in parallel with docs updates once chip-view contract is frozen.
+  - Search mode / zero-result rescue tasks should start after context-rail patterns are stable.
+
+## Documentation Prerequisites
+- `docs/modules/ui/architecture.md`
+- `docs/modules/ui/search-chip-context-contract.md`
+- `docs/modules/ui/implementation_plan.md`
+- `docs/modules/advisory-ai/knowledge-search.md`
+
+## Delivery Tracker
+
+### FE-UX-001 - Search context rail and explainable chips
+Status: DONE
+Dependency: none
+Owners: Developer (FE), UX
+Task description:
+- Add a visible context rail to the global search panel that shows:
+  - current page context
+  - active domain focus
+  - most recent meaningful action on the current page
+- Upgrade chip rendering so suggestion chips can expose rationale text and suggestion intent/category instead of showing only raw query text.
+- Keep the layout compact enough for header search use while remaining legible on mobile.
+
+Completion criteria:
+- [x] Empty-state search renders a context rail with page/domain/last-action information when available.
+- [x] Suggestion chips can render rationale text from the shared chip contract.
+- [x] Unit and Playwright coverage validate the new UI behavior.
+
+### FE-UX-002 - Search modes across search and AdvisoryAI
+Status: DONE
+Dependency: FE-UX-001
+Owners: Developer (FE), UX
+Task description:
+- Introduce explicit operator modes for the search/advisory experience:
+  - `Find`
+  - `Explain`
+  - `Act`
+- Use the selected mode to influence chip ordering, Ask-AI prompts, and zero-result rescue actions.
+
+Completion criteria:
+- [x] Mode switch is visible and keyboard accessible.
+- [x] Search and Ask-AI handoff respect the selected mode.
+- [x] Docs describe mode behavior and fallback semantics.
+
+### FE-UX-003 - Zero-result rescue and reformulation UX
+Status: DONE
+Dependency: FE-UX-001
+Owners: Developer (FE), UX
+Task description:
+- Improve no-result and sparse-result states with guided recovery actions:
+  - broaden scope
+  - search related domains
+  - ask AdvisoryAI to reformulate
+  - retry with visible entities / current page focus
+
+Completion criteria:
+- [x] Zero-result states provide at least three recovery actions.
+- [x] Recovery actions record contextual intent for follow-up search quality analysis.
+- [x] Playwright tests cover rescue behavior end-to-end.
+
+### FE-UX-004 - AdvisoryAI evidence-first next-step cards
+Status: DONE
+Dependency: FE-UX-002
+Owners: Developer (FE), Developer (AdvisoryAI), UX
+Task description:
+- Upgrade AdvisoryAI responses to render structured next-step cards for common operator flows:
+  - search deeper
+  - inspect evidence chain
+  - compare policy impact
+  - open timeline / graph / VEX
+- Keep all actions explicit and provenance-linked.
+
+Completion criteria:
+- [x] AdvisoryAI can render at least two structured next-step card types.
+- [x] Cards preserve evidence-first behavior and do not hide provenance.
+- [x] Search return flows remain deterministic.
+
+### FE-UX-005 - Docs sync and rollout notes
+Status: DONE
+Dependency: FE-UX-001
+Owners: Documentation author, Project Manager
+Task description:
+- Update UI and AdvisoryAI docs with the new UX contract and rollout guidance.
+- Record rationale for the chosen quality UX direction and phased delivery order.
+
+Completion criteria:
+- [x] Architecture docs reflect context rail + explainable chip behavior.
+- [x] Sprint Decisions & Risks capture rollout tradeoffs.
+- [x] Execution log links implementation and verification evidence.
+
+## Execution Log
+| Date (UTC) | Update | Owner |
+| --- | --- | --- |
+| 2026-03-06 | Sprint created for quality UX improvements on top of contextual search/advisory groundwork. | Project Manager |
+| 2026-03-06 | FE-UX-001 started: implementing context rail and explainable suggestion chips in global search. | Developer (FE) |
+| 2026-03-06 | FE-UX-001 completed: added search context rail, explainable suggestion cards, shared registry presentation/reason contract, targeted Angular tests (19/19), and Playwright contextual-suggestions verification (3/3). | Developer (FE) |
+| 2026-03-06 | FE-UX-002 completed: added shared `Find`/`Explain`/`Act` mode state, keyboard-accessible mode switchers in search and AdvisoryAI, and mode-aware search-to-chat handoff prompts. | Developer (FE) |
+| 2026-03-06 | FE-UX-003 completed: added zero-result rescue actions for scope broadening, related pivots, page-context retry, and AdvisoryAI reformulation; fixed search-panel focus containment so internal controls do not collapse the surface. | Developer (FE) |
+| 2026-03-06 | FE-UX-004 completed: AdvisoryAI assistant messages now render evidence-first next-step cards (search, evidence, policy, context) and return structured search intent back into global search deterministically. | Developer (FE) |
+| 2026-03-06 | FE-UX-005 completed: updated UI and AdvisoryAI docs, added targeted Angular coverage (39/39), and passed Playwright behavioral suites for contextual suggestions plus quality UX flows (7/7). | Developer (FE) |
+
+## Decisions & Risks
+- Decision: the first quality UX slice will prioritize explainability over more hidden ranking logic.
+- Decision: chip rationale should come from the shared registry/service contract, not component-local hardcoding.
+- Decision: executable suggestion text and visible rationale must stay separate so clicking a chip always submits only the intended query string.
+- Decision: search/advisory mode is a shared operator state (`Find`, `Explain`, `Act`) and not a local cosmetic toggle; prompts, chip ranking, and rescue actions all consume the same mode service.
+- Decision: focus transitions inside the global-search surface must not collapse the panel; mode switches, scope toggles, and rescue buttons are part of the same command surface.
+- Decision: AdvisoryAI next-step cards remain evidence-first by always exposing a direct evidence/open-context path in addition to search pivots.
+- Risk: richer chip content may overcrowd the header search dropdown.
+- Mitigation: use compact rail layout, limit visible chips, and keep rationale to a single short line.
+- Risk: page/domain labels can drift from actual route behavior.
+- Mitigation: derive labels from the same shared registry used for suggestion selection and context-rail presentation.
+- Risk: explicit mode state can drift between search and chat if separate stores are introduced.
+- Mitigation: keep a single root `SearchExperienceModeService` and verify handoff behavior in unit and Playwright coverage.
+
+## Next Checkpoints
+- 2026-03-07: FE-UX-001 through FE-UX-005 shipped and verified.
+- 2026-03-09: Monitor search/advisory telemetry for rescue-action usage and mode adoption.
+- 2026-03-11: Use field feedback to decide whether to add richer per-page card presets beyond search/policy/evidence/context.

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

@@ -123,6 +123,7 @@ Implemented in `src/AdvisoryAI/StellaOps.AdvisoryAI/KnowledgeSearch/KnowledgeSea
   - Global search emits ambient context with each unified query: `currentRoute`, `visibleEntityKeys`, `recentSearches`, `sessionId`, and optional `lastAction` (`action`, `source`, `queryHint`, `domain`, `entityKey`, `route`, `occurredAt`).
   - Contract remains backward-compatible: if an API deployment does not yet consume `lastAction`, unknown ambient fields are ignored and base search behavior remains unchanged.
   - UI suggestion behavior now combines obvious route defaults with one strategic non-obvious suggestion and action-aware variants (for example, policy/VEX impact and incident timeline pivots).
+  - Search and AdvisoryAI also share a persisted operator mode (`Find`, `Explain`, `Act`); the UI uses the same mode to rank chips, compose Ask-AI prompts, and label assistant return flows, while backend query contracts remain backward-compatible.
 - Unified index lifecycle:
   - Manual rebuild endpoint: `POST /v1/search/index/rebuild`.
   - Optional background refresh loop is available via `KnowledgeSearchOptions` (`UnifiedAutoIndexEnabled`, `UnifiedAutoIndexOnStartup`, `UnifiedIndexRefreshIntervalSeconds`).
@@ -170,6 +171,9 @@ Global search now consumes AKS and supports:
   - API: `Curl` (copy command).
   - Doctor: `Run` (navigate to doctor and copy run command).
 - `More` action for "show more like this" local query expansion.
+- A shared mode switch (`Find`, `Explain`, `Act`) across search and AdvisoryAI with mode-aware chip ranking and handoff prompts.
+- Zero-result rescue actions that keep the current query visible while broadening scope, trying a related pivot, retrying with page context, or opening AdvisoryAI reformulation.
+- AdvisoryAI evidence-first next-step cards that can return search pivots (`chat_next_step_search`, `chat_next_step_policy`) back into global search or open cited evidence/context directly.
 - Search-quality metrics taxonomy is standardized on `query`, `click`, and `zero_result` event types (no legacy `search` event dependency in quality SQL).
 - Synthesis usage is tracked via dedicated `synthesis` analytics events, while quality aggregates continue to compute totals from `query` + `zero_result`.
 - Quality dashboard query dimensions are exposed as query hashes (not raw query text) for privacy-preserving analytics.

docs/modules/ui/TASKS.md

@@ -3,6 +3,7 @@
 ## Active Sprint Links
 - `docs/implplan/SPRINT_20260221_041_FE_prealpha_ia_ops_setup_rewire.md`
 - `docs/implplan/SPRINT_20260306_001_Web_contextual_search_suggestions.md`
+- `docs/implplan/SPRINT_20260306_002_FE_search_advisory_quality_ux.md`
 
 ## Delivery Tasks
 - [DONE] 041-T1 Root IA/nav rewrite (Mission Control + Ops + Setup)
@@ -21,5 +22,13 @@
 - [DONE] WEB-CTX-003 FE -> AdvisoryAI ambient payload activation
 - [DOING] WEB-CTX-005 Context-aware suggestion UX updates
 - [DOING] WEB-CTX-007 Docs sync and rollout plan
+- [DONE] WEB-CTX-005A Playwright exhaustive query matrix (>1000 query types)
+- [DONE] FE-UX-001 Search context rail and explainable chips
+- [DONE] FE-UX-002 Search/AdvisoryAI shared mode switch (`Find` / `Explain` / `Act`)
+- [DONE] FE-UX-003 Zero-result rescue and reformulation UX
+- [DONE] FE-UX-004 AdvisoryAI evidence-first next-step cards
+- [DONE] FE-UX-005 Docs sync and rollout notes for search/advisory quality UX
 - [DONE] WEB-CTX-E2E Playwright coverage for contextual suggestions + ambient last-action payload
+- [DONE] FE-UX-E2E Playwright coverage for mode switching, rescue flows, and AdvisoryAI next-step cards
 - [DONE] WEB-CTX-NONOBVIOUS Strategic non-obvious suggestion recipes (cross-domain + action-aware)
+- [DOING] FE-QA-LOOP-001 Web-only Playwright full-iteration loop at stella-ops.local (fresh route/action evidence, triage, fix, retest)

docs/modules/ui/architecture.md

@@ -194,8 +194,14 @@ Each feature folder builds as a **standalone route** (lazy loaded). All HTTP sha
 * **Assistant -> search return**: assistant responses expose `Search for more` and `Search related` actions; these populate global search query/domain context and focus the search surface.
 * **Guided discovery empty state**: when global search is focused with an empty query, the panel renders an 8-domain guide (findings, VEX, policy, docs, API, health, operations, timeline), contextual suggestion chips, and quick actions (`Getting Started`, `Run Health Check`, `View Recent Scans`).
 * **Automatic page-open suggestions**: `AmbientContextService` tracks router navigation and updates global-search suggestion chips/placeholders automatically for every opened page without requiring manual refresh.
+* **Context rail**: empty-state search also renders a compact rail showing the current page title/description, active domain scope, and last meaningful action on the same page scope when available.
 * **Last-action follow-up suggestions**: the same service keeps a per-route scoped last action (search result open/action, Ask AI handoff, chat return actions) with deterministic TTL bounds; empty-state chips prepend a contextual `follow up: ...` suggestion when available.
 * **Strategic non-obvious suggestions**: each page scope injects at least one cross-domain guidance query (for example, findings -> policy/VEX impact, policy -> impacted findings, doctor -> release blockers) and switches to action-aware variants after meaningful user actions.
+* **Explainable chips**: suggestion queries remain short and executable, while a separate rationale line explains whether a chip comes from page defaults, recent actions, or strategic cross-domain guidance.
+* **Shared operator modes**: global search and AdvisoryAI share one persisted mode state (`Find`, `Explain`, `Act`) via `SearchExperienceModeService`; the mode changes chip ordering, Ask-AI prompts, empty-state starters, and structured next-step behavior.
+* **Zero-result rescue loop**: no-result states must expose recovery actions for broadening scope, trying a related pivot, retrying with page context, and opening AdvisoryAI reformulation with the active mode and query context preserved.
+* **Search-surface focus rule**: focus movement into controls inside the global-search surface (mode buttons, scope toggle, rescue buttons, filters) must not collapse the panel; the surface behaves like one command workspace rather than a disposable tooltip.
+* **AdvisoryAI next-step cards**: assistant responses with citations render structured cards for evidence inspection, context navigation, deeper search, and policy pivots; search-return actions must emit deterministic `chat_next_step_*` metadata back into global search.
 * **Ambient payload activation**: each global search request sends ambient context (`currentRoute`, `visibleEntityKeys`, `recentSearches`, `sessionId`, optional `lastAction`) so AdvisoryAI can apply contextual ranking/refinement.
 * **Chip contract governance**: page-owned chip arrays and route mappings are defined by `docs/modules/ui/search-chip-context-contract.md` and implemented in `search-context.registry.ts`.
 * **Fallback transparency**: when unified search drops to legacy fallback, global search displays an explicit degraded banner and emits enter/exit telemetry markers for operator visibility.

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

@@ -11,14 +11,22 @@
 - Context definitions must provide:
   - `id`
   - `routePrefixes`
+  - `presentation` (`titleKey/titleFallback`, `descriptionKey/descriptionFallback`) for the search context rail
   - optional `domain`
   - optional `searchSuggestions[]`
   - optional `chatSuggestions[]`
   - optional `chatRoutePattern`
+- Search suggestion entries should provide:
+  - `key` / `fallback` for the executable query text
+  - `reasonKey` / `reasonFallback` for the visible "why this suggestion" line
+  - optional `kind` (`page`, `recent`, `strategy`) when page teams need non-default styling/priority
+  - optional `preferredModes` (`find`, `explain`, `act`) when a chip should rank higher for a specific operator intent
 - 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
+  - keep the query label distinct from rationale text so suggestion clicks always submit the intended query only
+  - fallback copy should still make sense after mode-aware reordering; do not encode mode-specific rationale into the raw query text
 
 ## Source of truth
 - Contract and registry:
@@ -27,17 +35,35 @@
   - `src/Web/StellaOps.Web/src/app/core/services/ambient-context.service.ts`
 
 ## Runtime behavior
+- The empty-state search panel renders a context rail with:
+  - page title/description from `presentation`
+  - active domain token when available
+  - last-action token when recent scoped action history exists
 - 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.
+- Generated chips must also expose rationale metadata:
+  - `recent` chips explain they came from last-page actions
+  - `strategy` chips explain they came from recent intent on the same page scope
+- Mode-aware ranking:
+  - the shared `SearchExperienceModeService` owns the active operator mode
+  - chips marked with `preferredModes` are ranked ahead of otherwise-equal chips for that mode
+  - page teams should use this sparingly to express clear intent differences, not to create large per-mode chip forks
+- Search-surface control rule:
+  - buttons inside the search surface (mode switch, scope toggle, rescue cards, filters) are part of the same command workspace
+  - focus transitions into those controls must not collapse the search panel
+  - teams adding new controls inside the panel must preserve this containment rule in tests
 
 ## 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.
+3. Define or update `presentation` copy for the context rail.
+4. Add or update `reasonFallback` text and any `preferredModes` metadata for each base chip.
+5. Add/adjust unit tests in `ambient-context.service.spec.ts`.
+6. Add/adjust Playwright tests for route chips + action-driven chips.
+7. If the page adds custom controls inside the search panel, add focus-containment coverage so those controls do not dismiss the panel.
 
 ## Non-goals
 - No unbounded per-page suggestion memory.