feat(assistant): implement spec 021 chat assistant flow with semantic contracts

specs/021-llm-project-assistant/ux_reference.md

@@ -0,0 +1,84 @@
+# UX Reference: LLM Chat Assistant for Project Operations
+
+**Feature Branch**: `021-llm-project-assistant`
+**Created**: 2026-02-23  
+**Status**: Draft
+
+## 1. User Persona & Context
+
+* **Who is the user?**: Platform operator, dashboard engineer, or admin managing Superset operations.
+* **What is their goal?**: Execute routine and critical project operations quickly via natural language with safe controls.
+* **Context**: User is already in `ss-tools` web interface and wants to avoid jumping between Git, migration, backup, and task pages.
+
+## 2. The "Happy Path" Narrative
+
+The user opens assistant chat from the main interface and enters a natural command to run an operation. Assistant immediately recognizes intent, validates permissions, and either executes directly or asks for confirmation if operation is risky. For long-running actions, assistant responds instantly with `task_id` and where to track progress. User can ask follow-up status questions in the same chat and receives concise operational answers.
+
+## 3. Interface Mockups
+
+### UI Layout & Flow (if applicable)
+
+**Screen/Component**: Assistant Chat Panel
+
+* **Layout**:
+  - Right-side drawer or modal panel with message history.
+  - Input area at bottom with send action and command examples shortcut.
+  - Message cards with role (User/Assistant), timestamp, state badge.
+* **Key Elements**:
+  * **Chat Input**: Supports free-text commands in RU/EN.
+  * **State Badge**: `started`, `success`, `failed`, `needs_confirmation`, `denied`.
+  * **Confirmation Card**: Explicit confirm/cancel buttons for risky actions.
+  * **Task Link Chip**: `task_id` chip with quick open in Task Drawer.
+  * **Suggestions Block**: "Try command" examples for supported domains.
+* **States**:
+  * **Default**: Empty or recent history shown, examples visible.
+  * **Parsing**: Inline "Analyzing command..." loading state.
+  * **Needs Confirmation**: Warning card with operation summary and target environment.
+  * **Started**: Immediate message with `task_id` and tracking hint.
+  * **Error**: Error card with reason and recovery suggestion.
+
+### Interaction Examples
+
+```text
+User: запусти миграцию с dev на prod для дашборда 42
+Assistant: Операция рискованная (target=production). Подтвердите запуск.
+[Confirm] [Cancel]
+
+User: confirm
+Assistant: Миграция запущена. task_id=task-8f13. Прогресс: Task Drawer / Reports.
+```
+
+## 4. The "Error" Experience
+
+**Philosophy**: Never silently fail. Show what happened, why, and what to do next.
+
+### Scenario A: Ambiguous Command
+
+* **User Action**: "сделай задачу для дашборда 42"
+* **System Response**:
+  * Assistant does not execute immediately.
+  * Returns clarification question with options (Git branch / migration / backup / analysis).
+* **Recovery**: User selects one option or reformulates command.
+
+### Scenario B: Permission Denied
+
+* **User Action**: Non-admin requests production deploy.
+* **System Response**:
+  * Assistant returns `denied` state with minimal permission reason.
+  * No task is created.
+* **Recovery**: User requests access or uses allowed operation.
+
+### Scenario C: Confirmation Timeout
+
+* **System Response**: "Confirmation expired. Operation was not executed."
+* **Recovery**: User reissues command.
+
+### Scenario D: Downstream Failure After Start
+
+* **System Response**: Assistant returns `task_id` and indicates task moved to failed state with short error summary.
+* **Recovery**: Open task logs/reports using provided link/action.
+
+## 5. Tone & Voice
+
+* **Style**: Operational, concise, explicit.
+* **Terminology**: Use "command", "task", "confirmation", "status", "task_id"; avoid vague wording.