documentation cleanse, sprints work and planning. remaining non EF DAL migration to EF

docs/modules/advisory-ai/chat-interface.md

@@ -2,7 +2,7 @@
 
 > **Sprint:** SPRINT_20260107_006_003 Task CH-016
 > **Status:** Active
-> **Last Updated:** 2026-01-13
+> **Last Updated:** 2026-02-24
 
 The AdvisoryAI Chat Interface provides a conversational experience for security operators to investigate vulnerabilities, understand findings, and take remediation actions—all grounded in internal evidence with citations.
 
@@ -29,11 +29,21 @@ The chat interface enables:
 
 ## API Reference
 
+### Endpoint Families and Migration Timeline
+
+- Canonical chat surface: `/api/v1/chat/*`
+- Legacy compatibility surface: `/v1/advisory-ai/conversations*`
+- Legacy sunset date (UTC): **December 31, 2026**
+- Legacy responses emit migration headers:
+  - `Deprecation: true`
+  - `Sunset: Thu, 31 Dec 2026 23:59:59 GMT`
+  - `Link: </api/v1/chat/query>; rel="successor-version"`
+
 ### Create Conversation
 
 Creates a new conversation session.
 
-Required headers: `X-StellaOps-User`, `X-StellaOps-Client`, and either `X-StellaOps-Roles` (`chat:user` or `chat:admin`) or `X-StellaOps-Scopes` (`advisory:chat` or `advisory:run`).
+Required headers: `X-StellaOps-User`, `X-StellaOps-Client`, and either `X-StellaOps-Roles` (`chat:user` or `chat:admin`) or `X-StellaOps-Scopes` (`advisory-ai:view`, `advisory-ai:operate`, `advisory-ai:admin`, plus legacy `advisory:chat` / `advisory:run` aliases).
 
 ```http
 POST /v1/advisory-ai/conversations
@@ -88,6 +98,8 @@ X-StellaOps-Client: ui
 }
 ```
 
+`content` is the canonical add-turn payload field. A temporary compatibility shim still accepts legacy `message` input and maps it to `content`; empty/whitespace payloads return HTTP 400. Legacy `message` usage emits a warning header: `Warning: 299 - Legacy chat payload field 'message' is deprecated; use 'content'.`
+
 **Response (Server-Sent Events):**
 ```
 event: token
@@ -112,12 +124,14 @@ event: done
 data: {"turnId": "turn-xyz", "groundingScore": 0.92}
 ```
 
+Conversation add-turn responses now use the same grounded runtime path as the chat gateway. When runtime generation is unavailable, the service returns an explicit deterministic fallback response with metadata (no placeholder responses).
+
 ### Get Conversation
 
 Retrieves a conversation with its history.
 
 ```http
-GET /api/v1/advisory-ai/conversations/{conversationId}
+GET /v1/advisory-ai/conversations/{conversationId}
 Authorization: Bearer <token>
 ```
 
@@ -157,7 +171,7 @@ Authorization: Bearer <token>
 Lists conversations for a tenant/user.
 
 ```http
-GET /api/v1/advisory-ai/conversations?tenantId=tenant-123&userId=user-xyz&limit=20
+GET /v1/advisory-ai/conversations?tenantId=tenant-123&userId=user-xyz&limit=20
 Authorization: Bearer <token>
 ```
 
@@ -166,7 +180,7 @@ Authorization: Bearer <token>
 Deletes a conversation and its history.
 
 ```http
-DELETE /api/v1/advisory-ai/conversations/{conversationId}
+DELETE /v1/advisory-ai/conversations/{conversationId}
 Authorization: Bearer <token>
 ```
 
@@ -205,6 +219,9 @@ AI responses include object links that reference internal evidence. These links
 | Attestation | `[attest:dsse:{digest}]` | `[attest:dsse:sha256:xyz]` | Link to DSSE attestation |
 | Authority Key | `[auth:keys/{keyId}]` | `[auth:keys/gitlab-oidc]` | Link to signing key |
 | Documentation | `[docs:{path}]` | `[docs:scopes/ci-webhook]` | Link to documentation |
+| Finding | `[finding:{id}]` | `[finding:CVE-2024-12345]` | Link to finding detail |
+| Scan | `[scan:{id}]` | `[scan:scan-2026-02-24-001]` | Link to scan detail |
+| Policy | `[policy:{id}]` | `[policy:DENY-CRITICAL-PROD]` | Link to policy detail |
 
 ### Link Resolution
 
@@ -436,4 +453,3 @@ AdvisoryAI:
 - [Deployment Guide](deployment.md)
 - [Security Guardrails](/docs/security/assistant-guardrails.md)
 - [Controlled Conversational Interface Advisory](../../../docs-archived/product/advisories/13-Jan-2026%20-%20Controlled%20Conversational%20Interface.md)
-

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

@@ -130,6 +130,8 @@ Implemented in `src/AdvisoryAI/StellaOps.AdvisoryAI/KnowledgeSearch/KnowledgeSea
 - Query telemetry:
   - Unified search emits hashed query telemetry (`SHA-256` query hash, intent, domain weights, latency, top domains) via `IUnifiedSearchTelemetrySink`.
 - Web fallback behavior: when unified search fails, `UnifiedSearchClient` falls back to legacy AKS (`/v1/advisory-ai/search`) and maps grouped legacy results into unified cards (`diagnostics.mode = legacy-fallback`).
+  - UI now shows an explicit degraded-mode banner for `legacy-fallback` / `fallback-empty` modes and clears it automatically on recovery.
+  - Degraded-mode enter/exit transitions emit analytics markers (`__degraded_mode_enter__`, `__degraded_mode_exit__`); server-side search history intentionally ignores `__*` synthetic markers.
 
 ## Web behavior
 Global search now consumes AKS and supports:
@@ -140,6 +142,7 @@ 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.
+- Search-quality metrics taxonomy is standardized on `query`, `click`, and `zero_result` event types (no legacy `search` event dependency in quality SQL).
 
 ## CLI behavior
 AKS commands: