git.stella-ops.org/docs/modules/ui/search-zero-learning-primary-entry.md

# Search Zero-Learning Primary Entry

## Why this exists
- Search must be the default entry into Stella Ops for users who do not know Stella terminology, domain boundaries, or internal product structure.
- The current model asks the user to understand too many concepts before they can succeed: `Find/Explain/Act`, explicit scope switching, recovery actions, and a separate AdvisoryAI destination.
- Live verification also shows a real reliability gap: suggestion chips can render even when the active corpus cannot answer them. On 2026-03-07, the running AdvisoryAI service at `http://127.1.0.44` rebuilt with `documentCount=0`, `chunkCount=0`, and `doctorProjectionCount=0`, while unified overlays rebuilt with only `chunkCount=14`. Querying `database connectivity` then returned zero cards. The current UX still offered that suggestion.

## What still fails after the first pass
- The product still exposes two entry mental models: global search and a route-jumping AdvisoryAI experience. Search-originated chat actions currently navigate into `/security/triage`, which breaks page continuity and makes AdvisoryAI feel like a separate destination.
- The assistant still exposes `Find / Explain / Act` framing in chat. That pushes the user to learn the system's internal reasoning model instead of simply asking for help.
- Empty-state search still carries too much product education: domain guides, quick actions, context exposition, and explanatory labels. That is useful for experts but too loud for a self-serve default.
- Current-scope behavior is correct as a ranking concept, but the UI still talks about the mechanism instead of simply showing the best in-scope answer first and only then out-of-scope overflow.
- Suggestion reliability is fixed only when the active corpus is actually ingested. A healthy process with an empty corpus is still a bad operator experience unless the UI suppresses or fails those paths explicitly.

## What still fails after live operator use
- The product still leaves visible or hidden traces of a dual entry model. Search is supposed to be the starting point, but AdvisoryAI still feels like a separate feature instead of a secondary deep-dive opened from the search field.
- The current surface still carries internal search concepts in contracts and helpers even after the visible buttons were reduced. If `Find / Explain / Act` still changes prompt or chip behavior, the product is still teaching an internal model.
- The current history contract cannot reliably remove old failed searches after reload because the local store still accepts legacy bare-string entries with no result outcome attached.
- `Did you mean` is still visually tied to the results surface rather than the input correction moment. It needs to live immediately below the search field.
- Suggestions are still too easy to surface without enough corpus proof. Search must treat corpus readiness and suggestion executability as a product requirement, not a test-only concern.

## What still fails after direct operator usage
- Search and assistant still feel like sibling products in some flows. The operator should always start from search; assistant is a secondary detail view opened from that same surface.
- Any visible "scope" mechanic is wrong for the default path. Current route, visible entities, and recent actions should weight results automatically. If the best answer is outside the current page, show it as overflow only after trying the current page first.
- The product still risks teaching internal mechanics through labels, panels, and helper copy. The operator should not need to learn Stella structure, search science, or result modes just to get a useful answer.
- Suggestions are not acceptable unless they execute. A surfaced starter chip that leads to zero useful results is a product defect even when the service is healthy.
- When multiple high-confidence results are close, search should summarize them automatically. The assistant exists to expand and deepen the answer, not to compensate for a weak primary result.

## Product rules
1. Search is the primary entry point.
2. AdvisoryAI is a secondary deep-dive opened from search, not a competing starting point or route jump.
3. Search should infer relevance and intent; the user should not need to choose a mode or understand Stella search mechanics.
4. Search should bias to the current page context automatically; the user should not need to toggle scope.
5. Search should never advertise a suggestion that cannot execute against the active corpus.
6. Search history should contain only successful searches.
7. Telemetry remains optional. Search behavior must not depend on analytics emission.
8. Search UI must avoid teaching Stella terminology or search mechanics before the operator has even started.
9. `Did you mean` belongs directly below the search field because it is an input correction, not a downstream refinement.
10. Search should summarize close evidence automatically. AdvisoryAI expands detail; it should not be required to make the primary result understandable.
11. Search suggestions are only valid when end-to-end execution against the active ingested corpus returns a grounded or materially useful answer.
12. Search verification is incomplete until live ingestion-backed route coverage proves the surfaced suggestions on every supported page family.

## Target interaction model
### Entry
- Keep one primary search field in the top bar.
- Add a compact AdvisoryAI launcher icon beside the search input.
- Opening chat from that icon inherits the current page, current query, and top evidence when available.
- Opening chat must stay on the current page through a global drawer or equivalent shell-level host. Search should not navigate the operator into a different feature route just to ask follow-up questions.

### Query understanding
- Infer likely user intent from the query and visible page context.
- Weight current page/domain first.
- If current-scope evidence is weak, show overflow results from outside the page scope below the in-scope section instead of asking the user to broaden scope manually.

### Result presentation
- Place `Did you mean` directly below the input because it is an input correction, not a result refinement.
- Remove explicit `Find / Explain / Act` controls.
- Remove the explicit scope toggle chip.
- Remove manual result-domain refinements from the primary flow; the server should rank the current page first and render any cross-scope overflow as a secondary section instead.
- Remove the recovery panel.
- If top results are close in score, compose one short summary across them.
- If one result is clearly dominant, present that answer first and then cards.
- Prefer concise operator-facing labels over implementation-facing labels. The UI should show "best match here" and "also relevant elsewhere", not expose ranking jargon.
- Search-origin assistant actions should use secondary language such as "Open details" or "Ask for deeper help" rather than presenting a competing primary workflow.

### Suggestions
- Page suggestions become executable search intents, not static chips.
- A suggestion is only shown if:
  - its preferred domain has live evidence, or
  - the backend confirms non-zero candidate coverage for it.
- If the current corpus is empty for that page/domain, suppress those suggestion chips instead of showing dead leads.
- A preflight result is not enough on its own for release quality. The supported live routes must be verified by running the surfaced suggestions end to end against ingested data.

### History
- Persist and render only searches that returned results.
- Keep history clear as a low-emphasis icon action, not a labeled call-to-action.
- Existing history entries with zero results should be ignored on load so prior failed experiments do not pollute the empty state.

## Runtime rules
### Implicit scope weighting
- Current route/domain is a ranking boost, not a hard filter.
- Visible entity keys and last action increase local relevance.
- Out-of-scope results are still allowed, but only after in-scope candidates are exhausted or materially weaker.

### Answer blending
- If top-N cards fall within a narrow score band, emit a blended summary with citations from multiple cards.
- If score separation is strong, emit a single-result grounded answer.
- The frontend should not ask the user to choose whether they want `find` or `explain`; the backend should infer the dominant answer shape.

### Suggestion viability
- Suggestions must be validated against the current corpus before rendering.
- Knowledge/domain emptiness should be detectable so the UI can suppress invalid chips.
- Empty-state contextual chips and page-owned common-question chips should preflight through the backend viability endpoint before they render.
- Live Playwright coverage must assert that every surfaced suggestion returns visible results.
- A service health check alone is not enough. On 2026-03-07, `http://127.1.0.44/health` returned `200` while the live knowledge rebuild returned `documentCount=0`; the product still surfaced dead chips. Corpus readiness is the gate, not process liveness.

## Corrective execution phases
### Phase A - Search-first and assistant-second shell behavior
- Replace route-jumping chat opens with a global assistant drawer hosted by the shell.
- Remove mode switching from the assistant UI and prompt generation.
- Make the top-bar search icon the canonical assistant entry from any page.

### Phase B - Zero-learning search surface collapse
- Remove or minimize empty-state product education that teaches Stella structure instead of solving the current question.
- Keep `Did you mean` immediately under the input and keep overflow presentation subtle.
- Keep suggestions executable, short, and page-aware without extra explanation burden.

### Phase C - Ranking, answer blending, and optional telemetry
- Refine current-page/entity/action weighting so in-scope answers dominate when sensible.
- Blend answers only when the top evidence cluster is genuinely close; otherwise show a decisive primary answer.
- Ensure analytics, feedback, and quality telemetry can be disabled without breaking search, suggestions, history, or chat handoff.

### Phase D - Live ingestion-backed reliability matrix
- Keep mock-backed E2E for deterministic UI shape.
- Add live ingested E2E for the actual suggestions and answer experience on supported domains.
- Fail fast when corpus rebuild/readiness is missing so dead suggestions are treated as setup failures, not flaky UI tests.

## Current state
- Implemented from the corrective phases: search now opens AdvisoryAI through a shell-level drawer with no route jump, restores focus back to search when the drawer closes, and removes visible assistant mode framing.
- Implemented from the corrective phases: the empty state no longer teaches Stella taxonomy through domain guides or quick links; it now keeps only current-page context, successful recent searches, and executable starter chips.
- Implemented before and during the corrective phases: explicit scope/mode/recovery controls were removed from the main search flow, implicit current-scope weighting and overflow contracts were added, and suggestion viability preflight now suppresses dead chips before render.
- Implemented before the corrective phases: the live Doctor suggestion suite now rebuilds the active corpus, fails on empty knowledge projections, iterates every surfaced suggestion, and verifies Ask-AdvisoryAI inherits the live search context.
- Implemented from the corrective phases: backend overflow is now narrow enough that clear in-scope winners suppress out-of-scope spillover, blended summaries only appear for genuinely close evidence clusters, and `SearchTelemetryEnabled` cleanly disables analytics/feedback/sink emission without affecting retrieval or history.
- Implemented from the operator-correction pass: FE search contracts no longer depend on hidden `Find / Explain / Act` metadata, starter chips wait for backend viability before rendering, `Did you mean` is the first in-panel cue under the search field, and successful recent history now uses a structured `stella-successful-searches-v3` contract that ignores legacy bare-string entries on load.
- Implemented from the final correction pass: the primary surface now uses secondary "deeper help/details" assistant language instead of presenting a separate AdvisoryAI product, overflow results read as supporting context, and starter chips that execute to no useful result are suppressed from the current page until context changes.
- Still pending from the corrective phases: stricter backend viability states across more domains, broader live-page matrices, and explicit client-side telemetry opt-out.

## Execution phases - operator correction pass
### Phase 1 - Search-first primary surface cleanup
- Remove the remaining FE mode concept from shared search contracts, prompt helpers, and page-owned chip selection.
- Keep one visible primary entry: search input with a compact assistant launcher beside it.
- Attach `Did you mean` directly to the input area and simplify result labels to plain operator language.
- Migrate recent history to a structured success-only format and ignore legacy failed entries on load.

### Phase 2 - Backend query understanding and suggestion hardening
- Infer answer shape from the query, route context, visible entities, and recent actions instead of any FE mode hint.
- Return stricter suggestion viability signals so FE can suppress dead suggestions when the corpus is empty, stale, or outside the current route's supported domains.
- Keep out-of-scope overflow secondary and only when it materially improves the answer.
- Keep telemetry optional and separate from retrieval, ranking, suggestion gating, and history.
- Treat clarify-only suggestion candidates as non-executable; only grounded suggestions should survive preflight into the visible chip lane.

### Phase 3 - Live ingestion-backed readiness and regression gate
- Run deterministic Playwright against the simplified surface on every change.
- Run live Playwright against ingested corpora and fail early on empty corpus, missing rebuilds, or uncompiled CLI assumptions.
- Assert that every surfaced suggestion on covered routes resolves to a non-dead-end state.
- Treat corpus readiness as part of release verification for search suggestions.

## Final corrective pass
### Phase 4 - Search-first shell consolidation
- Keep one primary operator entry in the top bar: the search field.
- Keep the assistant available from a compact secondary icon beside the search field and from grounded answers, not as a competing entry model.
- Reduce primary-surface assistant branding so the product reads as one experience: search first, deeper help second.
- Remove or down-rank shell affordances that look like explicit scope controls when they only expose context.

### Phase 5 - Automatic answer shaping and weighted overflow
- Rank current-page evidence first using route, entity, and recent-action weighting without exposing that mechanism.
- When top results are genuinely close, compose one short grounded summary across them with citations.
- When one result is clearly dominant, show that answer first and push everything else down into supporting cards.
- Keep overflow secondary and quiet; it should feel like helpful spillover, not a mode or refinement path.

### Phase 6 - Suggestion executability proof across supported routes
- Extend live ingestion-backed verification beyond the Doctor page into findings, policy, and VEX-supported routes.
- Every surfaced starter chip on covered routes must execute successfully in Playwright against rebuilt corpora.
- Empty or unsupported corpora must suppress suggestions explicitly instead of letting the UI guess.

## Non-negotiable release checks
- Search must remain usable with telemetry disabled.
- Search history must persist only successful searches.
- Search must never require the operator to choose a mode or a scope.
- `Did you mean` must remain input-adjacent.
- Surfaced suggestions on supported live routes must be proven executable against ingested corpora before the search UX can be considered release-ready.