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)
-