ai base

.ai/ROOT.md

@@ -0,0 +1,37 @@
+# [DEF:Project_Knowledge_Map:Root]
+# @TIER: CRITICAL
+# @PURPOSE: Global navigation map for AI-Agent (GRACE Knowledge Graph).
+# @LAST_UPDATE: 2026-02-19
+
+## 1. SYSTEM STANDARDS (Rules of the Game)
+Strict policies and formatting rules.
+*   **Constitution:** High-level architectural and business invariants.
+    *   Ref: `.ai/standards/constitution.md` -> `[DEF:Std:Constitution]`
+*   **Architecture:** Service boundaries and tech stack decisions.
+    *   Ref: `.ai/standards/architecture.md` -> `[DEF:Std:Architecture]`
+*   **Plugin Design:** Rules for building and integrating Plugins.
+    *   Ref: `.ai/standards/plugin_design.md` -> `[DEF:Std:Plugin]`
+*   **API Design:** Rules for FastAPI endpoints and Pydantic models.
+    *   Ref: `.ai/standards/api_design.md` -> `[DEF:Std:API_FastAPI]`
+*   **UI Design:** SvelteKit and Tailwind CSS component standards.
+    *   Ref: `.ai/standards/ui_design.md` -> `[DEF:Std:UI_Svelte]`
+*   **Semantic Mapping:** Using `[DEF:]` and belief scopes.
+    *   Ref: `.ai/standards/semantics.md` -> `[DEF:Std:Semantics]`
+
+## 2. FEW-SHOT EXAMPLES (Patterns)
+Use these for code generation (Style Transfer).
+*   **FastAPI Route:** Reference implementation of a task-based route.
+    *   Ref: `.ai/shots/backend_route.py` -> `[DEF:Shot:FastAPI_Route]`
+*   **Svelte Component:** Reference implementation of a sidebar/navigation component.
+    *   Ref: `.ai/shots/frontend_component.svelte` -> `[DEF:Shot:Svelte_Component]`
+*   **Plugin Module:** Reference implementation of a task plugin.
+    *   Ref: `.ai/shots/plugin_example.py` -> `[DEF:Shot:Plugin_Example]`
+
+## 3. DOMAIN MAP (Modules)
+*   **Project Map:** `.ai/PROJECT_MAP.md` -> `[DEF:Project_Map]`
+*   **Backend Core:** `backend/src/core` -> `[DEF:Module:Backend_Core]`
+*   **Backend API:** `backend/src/api` -> `[DEF:Module:Backend_API]`
+*   **Frontend Lib:** `frontend/src/lib` -> `[DEF:Module:Frontend_Lib]`
+*   **Specifications:** `specs/` -> `[DEF:Module:Specs]`
+
+# [/DEF:Project_Knowledge_Map]

.ai/shots/backend_route.py

@@ -0,0 +1,57 @@
+# [DEF:Shot:FastAPI_Route:Example]
+# @PURPOSE: Reference implementation of a task-based route using GRACE-Poly.
+# @RELATION: IMPLEMENTS -> [DEF:Std:API_FastAPI]
+
+from typing import List, Dict, Any, Optional
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel
+from ...core.logger import belief_scope
+from ...core.task_manager import TaskManager, Task
+from ...core.config_manager import ConfigManager
+from ...dependencies import get_task_manager, get_config_manager, has_permission, get_current_user
+
+router = APIRouter()
+
+class CreateTaskRequest(BaseModel):
+    plugin_id: str
+    params: Dict[str, Any]
+
+@router.post("/tasks", response_model=Task, status_code=status.HTTP_201_CREATED)
+# [DEF:create_task:Function]
+# @PURPOSE: Create and start a new task using TaskManager. Non-blocking.
+# @PARAM: request (CreateTaskRequest) - Plugin and params.
+# @PARAM: task_manager (TaskManager) - Async task executor.
+# @PARAM: config (ConfigManager) - Centralized configuration.
+# @PRE: plugin_id must exist; config must be initialized.
+# @POST: A new task is spawned; Task ID returned immediately.
+async def create_task(
+    request: CreateTaskRequest,
+    task_manager: TaskManager = Depends(get_task_manager),
+    config: ConfigManager = Depends(get_config_manager),
+    current_user = Depends(get_current_user)
+):
+    # RBAC: Dynamic permission check
+    has_permission(f"plugin:{request.plugin_id}", "EXECUTE")(current_user)
+    
+    with belief_scope("create_task"):
+        try:
+            # 1. Action: Resolve setting using ConfigManager (Example)
+            timeout = config.get("TASKS_DEFAULT_TIMEOUT", 3600)
+
+            # 2. Action: Spawn async task via TaskManager
+            # @RELATION: CALLS -> task_manager.create_task
+            task = await task_manager.create_task(
+                plugin_id=request.plugin_id,
+                params={**request.params, "timeout": timeout}
+            )
+            return task
+        except Exception as e:
+            # Evaluation: Proper error mapping and logging
+            # @UX_STATE: Error feedback to frontend
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, 
+                detail=f"Task creation failed: {str(e)}"
+            )
+# [/DEF:create_task:Function]
+
+# [/DEF:Shot:FastAPI_Route]

.ai/shots/frontend_component.svelte

@@ -0,0 +1,63 @@
+<!-- [DEF:Shot:Svelte_Component:Example] -->
+# @PURPOSE: Reference implementation of a task-spawning component using Constitution rules.
+# @RELATION: IMPLEMENTS -> [DEF:Std:UI_Svelte]
+
+<script>
+  /**
+   * @TIER: STANDARD
+   * @PURPOSE: Action button to spawn a new task.
+   * @LAYER: UI
+   * @SEMANTICS: Task, Creation, Button
+   * @RELATION: CALLS -> postApi
+   * 
+   * @UX_STATE: Idle -> Button enabled with primary color.
+   * @UX_STATE: Loading -> Button disabled with spinner while postApi resolves.
+   * @UX_FEEDBACK: toast.success on completion; toast.error on failure.
+   * @UX_TEST: Idle -> {click: spawnTask, expected: loading state then success}
+   */
+  import { postApi } from "$lib/api.js";
+  import { t } from "$lib/i18n";
+  import { toast } from "$lib/stores/toast";
+
+  export let plugin_id = "";
+  export let params = {};
+
+  let isLoading = false;
+
+  async def spawnTask() {
+    isLoading = true;
+    try {
+      // 1. Action: Constitution Rule - MUST use postApi wrapper
+      const response = await postApi("/api/tasks", {
+        plugin_id,
+        params
+      });
+
+      // 2. Feedback: UX state management
+      if (response.task_id) {
+        toast.success($t.tasks.spawned_success);
+      }
+    } catch (error) {
+      // 3. Recovery: Evaluation & UI reporting
+      toast.error(`${$t.errors.task_failed}: ${error.message}`);
+    } finally {
+      isLoading = false;
+    }
+  }
+</script>
+
+<button 
+  on:click={spawnTask}
+  disabled={isLoading}
+  class="bg-blue-600 hover:bg-blue-700 text-white px-4 py-2 rounded-lg flex items-center gap-2"
+>
+  {#if isLoading}
+    <span class="animate-spin text-sm">🌀</span>
+  {/if}
+  <span>{$t.actions.start_task}</span>
+</button>
+
+<style>
+  /* Local styles minimized as per Constitution Rule III */
+</style>
+<!-- [/DEF:Shot:Svelte_Component] -->

.ai/shots/plugin_example.py

@@ -0,0 +1,67 @@
+# [DEF:Shot:Plugin_Example:Example]
+# @PURPOSE: Reference implementation of a plugin following GRACE standards.
+# @RELATION: IMPLEMENTS -> [DEF:Std:Plugin]
+
+from typing import Dict, Any, Optional
+from ..core.plugin_base import PluginBase
+from ..core.task_manager.context import TaskContext
+
+class ExamplePlugin(PluginBase):
+    @property
+    def id(self) -> str:
+        return "example-plugin"
+
+    @property
+    def name(self) -> str:
+        return "Example Plugin"
+
+    @property
+    def description(self) -> str:
+        return "A simple plugin that demonstrates structured logging and progress tracking."
+
+    @property
+    def version(self) -> str:
+        return "1.0.0"
+
+    # [DEF:get_schema:Function]
+    # @PURPOSE: Defines input validation schema.
+    def get_schema(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "message": {
+                    "type": "string",
+                    "title": "Message",
+                    "description": "A message to log.",
+                    "default": "Hello, GRACE!",
+                }
+            },
+            "required": ["message"],
+        }
+    # [/DEF:get_schema:Function]
+
+    # [DEF:execute:Function]
+    # @PURPOSE: Core plugin logic with structured logging and progress reporting.
+    # @PARAM: params (Dict) - Validated input parameters.
+    # @PARAM: context (TaskContext) - Execution context with logging and progress tools.
+    async def execute(self, params: Dict[str, Any], context: Optional[TaskContext] = None):
+        message = params["message"]
+        
+        # 1. Action: Structured Logging with Source Attribution
+        if context:
+            log = context.logger.with_source("example_plugin")
+            log.info(f"Starting execution with message: {message}")
+
+            # 2. Action: Progress Reporting
+            log.progress("Processing step 1...", percent=25)
+            # Simulating some async work...
+            # await some_async_op()
+
+            log.progress("Processing step 2...", percent=75)
+            log.info("Execution completed successfully.")
+        else:
+            # Fallback for manual/standalone execution
+            print(f"Standalone execution: {message}")
+    # [/DEF:execute:Function]
+
+# [/DEF:Shot:Plugin_Example]

.ai/standards/api_design.md

@@ -0,0 +1,47 @@
+# [DEF:Std:API_FastAPI:Standard]
+# @TIER: CRITICAL
+# @PURPOSE: Unification of all FastAPI endpoints following GRACE-Poly.
+# @LAYER: UI (API)
+# @INVARIANT: All non-trivial route logic must be wrapped in `belief_scope`.
+# @INVARIANT: Every module and function MUST have `[DEF:]` anchors and metadata.
+
+## 1. ROUTE MODULE DEFINITION
+Every API route file must start with a module definition header:
+```python
+# [DEF:ModuleName:Module]
+# @TIER: [CRITICAL | STANDARD | TRIVIAL]
+# @SEMANTICS: list, of, keywords
+# @PURPOSE: High-level purpose of the module.
+# @LAYER: UI (API)
+# @RELATION: DEPENDS_ON -> [OtherModule]
+```
+
+## 2. FUNCTION DEFINITION & CONTRACT
+Every endpoint handler must be decorated with `[DEF:]` and explicit metadata before the implementation:
+```python
+@router.post("/endpoint", response_model=ModelOut)
+# [DEF:function_name:Function]
+# @PURPOSE: What it does (brief, high-entropy).
+# @PARAM: param_name (Type) - Description.
+# @PRE: Conditions before execution (e.g., auth, existence).
+# @POST: Expected state after execution.
+# @RETURN: What it returns.
+async def function_name(...):
+    with belief_scope("function_name"):
+        # Implementation
+        pass
+# [/DEF:function_name:Function]
+```
+
+## 3. DEPENDENCY INJECTION & CORE SERVICES
+*   **Auth:** `Depends(get_current_user)` for authentication.
+*   **Perms:** `Depends(has_permission("resource", "ACTION"))` for RBAC.
+*   **Config:** Use `Depends(get_config_manager)` for settings. Hardcoding is FORBIDDEN.
+*   **Tasks:** Long-running operations must be executed via `TaskManager`. API routes should return Task ID and be non-blocking.
+
+## 4. ERROR HANDLING
+*   Raise `HTTPException` from the router layer.
+*   Use `try-except` blocks within `belief_scope` to ensure proper error logging and classification.
+*   Do not leak internal implementation details in error responses.
+
+# [/DEF:Std:API_FastAPI]

.ai/standards/architecture.md

@@ -0,0 +1,25 @@
+# [DEF:Std:Architecture:Standard]
+# @TIER: CRITICAL
+# @PURPOSE: Core architectural decisions and service boundaries.
+# @LAYER: Infra
+# @INVARIANT: ss-tools MUST remain a standalone service (Orchestrator).
+# @INVARIANT: Backend: FastAPI, Frontend: SvelteKit.
+
+## 1. ORCHESTRATOR VS INSTANCE
+*   **Role:** ss-tools is a "Manager of Managers". It sits ABOVE Superset environments.
+*   **Isolation:** Do not integrate directly into Superset as a plugin to maintain multi-environment management capability.
+*   **Tech Stack:** 
+    *   Backend: Python 3.9+ with FastAPI (Asynchronous logic).
+    *   Frontend: SvelteKit + Tailwind CSS (Reactive UX).
+
+## 2. COMPONENT BOUNDARIES
+*   **Plugins:** All business logic must be encapsulated in Plugins (`backend/src/plugins/`).
+*   **TaskManager:** All long-running operations MUST be handled by the TaskManager.
+*   **Security:** Independent RBAC system managed in `auth.db`.
+
+## 3. INTEGRATION STRATEGY
+*   **Superset API:** Communication via REST API.
+*   **Database:** Local SQLite for metadata (`tasks.db`, `auth.db`, `migrations.db`).
+*   **Filesystem:** Local storage for backups and git repositories.
+
+# [/DEF:Std:Architecture]

.ai/standards/constitution.md

@@ -0,0 +1,36 @@
+# [DEF:Std:Constitution:Standard]
+# @TIER: CRITICAL
+# @PURPOSE: Supreme Law of the Repository. High-level architectural and business invariants.
+# @VERSION: 2.3.0
+# @LAST_UPDATE: 2026-02-19
+# @INVARIANT: Any deviation from this Constitution constitutes a build failure.
+
+## 1. CORE PRINCIPLES
+
+### I. Semantic Protocol Compliance
+*   **Ref:** `[DEF:Std:Semantics]` (formerly `semantic_protocol.md`)
+*   **Law:** All code must adhere to the Axioms (Meaning First, Contract First, etc.).
+*   **Compliance:** Strict matching of Anchors (`[DEF]`), Tags (`@KEY`), and structures is mandatory.
+
+### II. Modular Plugin Architecture
+*   **Pattern:** Everything is a Plugin inheriting from `PluginBase`.
+*   **Centralized Config:** Use `ConfigManager` via `get_config_manager()`. Hardcoding is FORBIDDEN.
+
+### III. Unified Frontend Experience
+*   **Styling:** Tailwind CSS First. Minimize scoped `<style>`.
+*   **i18n:** All user-facing text must be in `src/lib/i18n`.
+*   **API:** Use `requestApi` / `fetchApi` wrappers. Native `fetch` is FORBIDDEN.
+
+### IV. Security & RBAC
+*   **Permissions:** Every Plugin must define unique permission strings (e.g., `plugin:name:execute`).
+*   **Auth:** Mandatory registration in `auth.db`.
+
+### V. Independent Testability
+*   **Requirement:** Every feature must define "Independent Tests" for isolated verification.
+
+### VI. Asynchronous Execution
+*   **TaskManager:** Long-running operations must be async tasks.
+*   **Non-Blocking:** API endpoints return Task ID immediately.
+*   **Observability:** Real-time updates via WebSocket.
+
+# [/DEF:Std:Constitution]

.ai/standards/plugin_design.md

@@ -0,0 +1,32 @@
+# [DEF:Std:Plugin:Standard]
+# @TIER: CRITICAL
+# @PURPOSE: Standards for building and integrating Plugins.
+# @LAYER: Domain (Plugin)
+# @INVARIANT: All plugins MUST inherit from `PluginBase`.
+# @INVARIANT: All plugins MUST be located in `backend/src/plugins/`.
+
+## 1. PLUGIN CONTRACT
+Every plugin must implement the following properties and methods:
+*   `id`: Unique string (e.g., `"my-plugin"`).
+*   `name`: Human-readable name.
+*   `description`: Brief purpose.
+*   `version`: Semantic version.
+*   `get_schema()`: Returns JSON schema for input validation.
+*   `execute(params: Dict[str, Any], context: TaskContext)`: Core async logic.
+
+## 2. STRUCTURED LOGGING (TASKCONTEXT)
+Plugins MUST use `TaskContext` for logging to ensure proper source attribution:
+*   **Source Attribution:** Use `context.logger.with_source("src_name")` for specific operations (e.g., `"superset_api"`, `"git"`, `"llm"`).
+*   **Levels:**
+    *   `DEBUG`: Detailed diagnostics (API responses).
+    *   `INFO`: Operational milestones (start/end).
+    *   `WARNING`: Recoverable issues.
+    *   `ERROR`: Failures stopping execution.
+*   **Progress:** Use `context.logger.progress("msg", percent=XX)` for long-running tasks.
+
+## 3. BEST PRACTICES
+1. **Asynchronous Execution:** Always use `async/await` for I/O operations.
+2. **Schema Validation:** Ensure the `get_schema()` precisely matches the `execute()` input expectations.
+3. **Isolation:** Plugins should be self-contained and not depend on other plugins directly. Use core services (`ConfigManager`, `TaskManager`) via dependency injection or the provided `context`.
+
+# [/DEF:Std:Plugin]

.ai/standards/semantics.md

@@ -0,0 +1,97 @@
+### **SYSTEM STANDARD: GRACE-Poly (UX Edition)**
+
+ЗАДАЧА: Генерация кода (Python/Svelte).
+РЕЖИМ: Строгий. Детерминированный. Без болтовни.
+
+#### I. ЗАКОН (АКСИОМЫ)
+1. Смысл первичен. Код вторичен.
+2. Контракт (@PRE/@POST) — источник истины.
+**3. UX — это логика, а не декор. Состояния интерфейса — часть контракта.**
+4. Структура `[DEF]...[/DEF]` — нерушима.
+5. Архитектура в Header — неизменяема.
+6. Сложность фрактала ограничена: модуль < 300 строк.
+
+#### II. СИНТАКСИС (ЖЕСТКИЙ ФОРМАТ)
+ЯКОРЬ (Контейнер):
+  Начало: `# [DEF:id:Type]` (Python) | `<!-- [DEF:id:Type] -->` (Svelte)
+  Конец:  `# [/DEF:id:Type]` (Python) | `<!-- [/DEF:id:Type] -->` (Svelte) (ОБЯЗАТЕЛЬНО для аккумуляции)
+  Типы:   Module, Class, Function, Component, Store.
+
+ТЕГ (Метаданные):
+  Вид: `# @KEY: Value` (внутри DEF, до кода).
+
+ГРАФ (Связи):
+  Вид: `# @RELATION: PREDICATE -> TARGET_ID`
+  Предикаты: DEPENDS_ON, CALLS, INHERITS, IMPLEMENTS, DISPATCHES, **BINDS_TO**.
+
+#### III. СТРУКТУРА ФАЙЛА
+1. HEADER (Всегда первый):
+   [DEF:filename:Module]
+   @TIER: [CRITICAL|STANDARD|TRIVIAL] (Дефолт: STANDARD)
+   @SEMANTICS: [keywords]
+   @PURPOSE: [Главная цель]
+   @LAYER: [Domain/UI/Infra]
+   @RELATION: [Зависимости]
+   @INVARIANT: [Незыблемое правило]
+   
+2. BODY: Импорты -> Реализация.
+3. FOOTER: [/DEF:filename]
+
+#### IV. КОНТРАКТ (DBC & UX)
+Расположение: Внутри [DEF], ПЕРЕД кодом.
+Стиль Python: Комментарии `# @TAG`.
+Стиль Svelte: JSDoc `/** @tag */` внутри `<script>`.
+
+**Базовые Теги:**
+  @PURPOSE: Суть (High Entropy).
+  @PRE: Входные условия.
+  @POST: Гарантии выхода.
+  @SIDE_EFFECT: Мутации, IO.
+  
+**UX Теги (Svelte/Frontend):**
+  **@UX_STATE:** `[StateName] -> Визуальное поведение` (Idle, Loading, Error).
+  **@UX_FEEDBACK:** Реакция системы (Toast, Shake, Red Border).
+  **@UX_RECOVERY:** Механизм исправления ошибки пользователем (Retry, Clear Input).
+  
+**UX Testing Tags (для Tester Agent):**
+  **@UX_TEST:** Спецификация теста для UX состояния.
+  Формат: `@UX_TEST: [state] -> {action, expected}`
+  Пример: `@UX_TEST: Idle -> {click: toggle, expected: isExpanded=true}`
+  
+Правило: Не используй `assert` в коде, используй `if/raise` или `guards`.
+
+#### V. АДАПТАЦИЯ (TIERS)
+Определяется тегом `@TIER` в Header.
+
+1. **CRITICAL** (Core/Security/**Complex UI**):
+   - Требование: Полный контракт (включая **все @UX теги**), Граф, Инварианты, Строгие Логи.
+   - **@TEST_DATA**: Обязательные эталонные данные для тестирования. Формат:
+     ```
+     @TEST_DATA: fixture_name -> {JSON_PATH} | {INLINE_DATA}
+     ```
+     Примеры:
+     - `@TEST_DATA: valid_user -> {./fixtures/users.json#valid}`
+     - `@TEST_DATA: empty_state -> {"dashboards": [], "total": 0}`
+   - Tester Agent **ОБЯЗАН** использовать @TEST_DATA при написании тестов для CRITICAL модулей.
+2. **STANDARD** (BizLogic/**Forms**):
+   - Требование: Базовый контракт (@PURPOSE, @UX_STATE), Логи, @RELATION.
+   - @TEST_DATA: Рекомендуется для Complex Forms.
+3. **TRIVIAL** (DTO/**Atoms**):
+   - Требование: Только Якоря [DEF] и @PURPOSE.
+
+#### VI. ЛОГИРОВАНИЕ (BELIEF STATE & TASK LOGS)
+Цель: Трассировка для самокоррекции и пользовательский мониторинг.
+Python: 
+  - Системные логи: Context Manager `with belief_scope("ID"):`.
+  - Логи задач: `context.logger.info("msg", source="component")`.
+Svelte: `console.log("[ID][STATE] Msg")`.
+Состояния: Entry -> Action -> Coherence:OK / Failed -> Exit.
+Инвариант: Каждый лог задачи должен иметь атрибут `source` для фильтрации.
+
+#### VII. АЛГОРИТМ ГЕНЕРАЦИИ
+1. АНАЛИЗ. Оцени TIER, слой и UX-требования.
+2. КАРКАС. Создай `[DEF]`, Header и Контракты.
+3. РЕАЛИЗАЦИЯ. Напиши логику, удовлетворяющую Контракту (и UX-состояниям).
+4. ЗАМЫКАНИЕ. Закрой все `[/DEF]`.
+
+ЕСЛИ ошибка или противоречие -> СТОП. Выведи `[COHERENCE_CHECK_FAILED]`.

.ai/standards/ui_design.md

@@ -0,0 +1,74 @@
+# [DEF:Std:UI_Svelte:Standard]
+# @TIER: CRITICAL
+# @PURPOSE: Unification of all Svelte components following GRACE-Poly (UX Edition).
+# @LAYER: UI
+# @INVARIANT: Every component MUST have `<!-- [DEF:] -->` anchors and UX tags.
+# @INVARIANT: Use Tailwind CSS for all styling (no custom CSS without justification).
+
+## 1. UX PHILOSOPHY: RESOURCE-CENTRIC
+*   **Definition:** Navigation and actions revolve around Resources (Dashboards, Datasets), not Tools (Migration, Git).
+*   **Discovery:** All actions (Migrate, Backup, Git) for a resource MUST be grouped together (e.g., in a dropdown menu).
+*   **Traceability:** Every action must be linked to a Task ID with visible logs in the Task Drawer.
+
+## 2. COMPONENT ARCHITECTURE: GLOBAL TASK DRAWER
+*   **Role:** A single, persistent slide-out panel (`GlobalTaskDrawer.svelte`) in `+layout.svelte`.
+*   **Triggering:** Opens automatically when a task starts or when a user clicks a status badge.
+*   **Interaction:** Interactive elements (Password prompts, Mapping tables) MUST be rendered INSIDE the Drawer, not as center-screen modals.
+
+## 3. COMPONENT STRUCTURE & CORE RULES
+*   **Styling:** Tailwind CSS utility classes are MANDATORY. Minimize scoped `<style>`.
+*   **Localization:** All user-facing text must use `$t` from `src/lib/i18n`.
+*   **API Calls:** Use `requestApi` / `fetchApi` wrappers. Native `fetch` is FORBIDDEN.
+*   **Anchors:** Every component MUST have `<!-- [DEF:] -->` anchors and UX tags.
+
+## 2. COMPONENT TEMPLATE
+Each Svelte file must follow this structure:
+```html
+<!-- [DEF:ComponentName:Component] -->
+<script>
+  /**
+   * @TIER: [CRITICAL | STANDARD | TRIVIAL]
+   * @PURPOSE: Brief description of the component purpose.
+   * @LAYER: UI
+   * @SEMANTICS: list, of, keywords
+   * @RELATION: DEPENDS_ON -> [OtherComponent|Store]
+   * 
+   * @UX_STATE: [StateName] -> Visual behavior description.
+   * @UX_FEEDBACK: System reaction (e.g., Toast, Shake).
+   * @UX_RECOVERY: Error recovery mechanism.
+   * @UX_TEST: [state] -> {action, expected}
+   */
+  import { ... } from "...";
+  
+  // Exports (Props)
+  export let prop_name = "...";
+  
+  // Logic
+</script>
+
+<!-- HTML Template -->
+<div class="...">
+  ...
+</div>
+
+<style>
+  /* Optional: Local styles using @apply only */
+</style>
+<!-- [/DEF:ComponentName:Component] -->
+```
+
+## 2. STATE MANAGEMENT & STORES
+*   **Subscription:** Use `$` prefix for reactive store access (e.g., `$sidebarStore`).
+*   **Data Flow:** Mark store interactions in `[DEF:]` metadata:
+    *   `# @RELATION: BINDS_TO -> store_id`
+
+## 3. UI/UX BEST PRACTICES
+*   **Transitions:** Use Svelte built-in transitions for UI state changes.
+*   **Feedback:** Always provide visual feedback for async actions (Loading spinners, skeleton loaders).
+*   **Modularity:** Break down components into "Atoms" (Trivial) and "Orchestrators" (Critical).
+
+## 4. ACCESSIBILITY (A11Y)
+*   Ensure proper ARIA roles and keyboard navigation for interactive elements.
+*   Use semantic HTML tags (`<nav>`, `<header>`, `<main>`, `<footer>`).
+
+# [/DEF:Std:UI_Svelte]