@doderasoftware/restify-ai 0.1.0-beta.1 → 0.1.0-beta.11

package/README.md

@@ -1,514 +1,1050 @@
 # @doderasoftware/restify-ai
 
-> 🤖 A fully customizable Vue 3 AI chatbot component library with Laravel Restify integration
+A production-ready AI chatbot component for Vue 3 with real-time SSE streaming, file attachments, @mentions, and seamless [Laravel Restify](https://laravel-restify.com) integration.
 
-[![npm version](https://img.shields.io/npm/v/@doderasoftware/restify-ai)](https://www.npmjs.com/package/@doderasoftware/restify-ai)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/)
-[![Vue 3](https://img.shields.io/badge/Vue-3.x-brightgreen)](https://vuejs.org/)
+[![npm version](https://img.shields.io/npm/v/@doderasoftware/restify-ai.svg)](https://www.npmjs.com/package/@doderasoftware/restify-ai)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Vue 3](https://img.shields.io/badge/Vue-3.x-brightgreen.svg)](https://vuejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
+
+**📖 [Laravel Restify](https://laravel-restify.com) | 📦 [npm](https://www.npmjs.com/package/@doderasoftware/restify-ai) | 🏢 [BinarCode](https://binarcode.com)**
 
 ---
 
 ## ✨ Features
 
-| Feature | Description |
-|---------|-------------|
-| 🔌 **Laravel Restify** | Built for seamless Laravel Restify AI endpoints |
-| 📡 **SSE Streaming** | Real-time streaming responses with Server-Sent Events |
-| 📎 **File Attachments** | Built-in file upload with progress & preview |
-| 💬 **@Mentions** | Pluggable mention providers (employees, projects, etc.) |
-| 💡 **Smart Suggestions** | Route-aware suggestion system |
-| 🎨 **Fully Customizable** | UI classes, texts, slots, themes |
-| ⌨️ **Keyboard Shortcuts** | Configurable shortcuts (e.g., \`Cmd+G\`) |
-| 🔄 **Auto Retry** | Configurable retry logic with exponential backoff |
-| 💾 **Session Persistence** | Chat history survives page refresh |
-| 🌙 **Dark Mode** | Full dark mode support out of the box |
-| 📦 **Tree-shakable** | Import only what you need |
-| 🎯 **TypeScript** | Full TypeScript support |
-
----
+- 🌊 **Real-time SSE Streaming** - Smooth character-by-character response streaming
+- 📎 **File Attachments** - Upload and process documents, images, and more
+- 👥 **@Mentions System** - Reference entities from your application (employees, jobs, projects, etc.)
+- 💡 **Context-Aware Suggestions** - Smart prompts based on current page/route
+- 💬 **Chat History** - Persistent conversation memory with configurable limits
+- 📝 **Markdown Rendering** - Beautiful formatting with syntax highlighting
+- 📊 **Quota Management** - Track and display API usage limits
+- 🎨 **Fully Customizable** - Override any style with CSS classes
+- 🌙 **Dark Mode Support** - Automatic dark/light theme detection
+- 📱 **Responsive Design** - Works on desktop, tablet, and mobile
+- ⌨️ **Keyboard Shortcuts** - Quick access with configurable shortcuts
+- 🔳 **Fullscreen Mode** - Expandable chat interface
+- 🎯 **TypeScript First** - Full type definitions included
+- 🗃️ **Pinia Integration** - State management built-in
+- 🔧 **Slot-Based Customization** - Override any component section
+- 🌐 **i18n Ready** - Full internationalization support
+- 🆘 **Support Mode** - Route conversations to human support
+- 🔄 **Retry Logic** - Automatic retry with configurable backoff
 
 ## 📦 Installation
 
-\`\`\`bash
+```bash
 npm install @doderasoftware/restify-ai
-# or
-pnpm add @doderasoftware/restify-ai
-\`\`\`
+```
 
-**Peer Dependencies:** \`vue ^3.4\`, \`pinia ^2.1\`
+### Peer Dependencies
 
----
+```bash
+npm install vue@^3.3.0 pinia@^2.1.0
+```
 
 ## 🚀 Quick Start
 
-\`\`\`typescript
+### 1. Import Styles
+
+```typescript
+// main.ts
+import '@doderasoftware/restify-ai/styles'
+```
+
+### 2. Create Plugin Configuration
+
+```typescript
+// plugins/restifyAi.ts
+import type { App } from 'vue'
+import { RestifyAiPlugin } from '@doderasoftware/restify-ai'
+import '@doderasoftware/restify-ai/styles'
+
+export function setupRestifyAi(app: App) {
+  app.use(RestifyAiPlugin, {
+    endpoints: {
+      ask: '/ask',
+      uploadFile: '/ai/upload',
+      quota: '/ai/quota',
+    },
+    baseUrl: import.meta.env.VITE_API_URL,
+    getAuthToken: () => localStorage.getItem('token'),
+  })
+}
+```
+
+### 3. Register in Main
+
+```typescript
 // main.ts
 import { createApp } from 'vue'
 import { createPinia } from 'pinia'
-import { RestifyAiPlugin } from '@doderasoftware/restify-ai'
+import App from './App.vue'
+import { setupRestifyAi } from './plugins/restifyAi'
 import '@doderasoftware/restify-ai/styles'
 
 const app = createApp(App)
 app.use(createPinia())
-
-app.use(RestifyAiPlugin, {
-  endpoints: {
-    ask: '/api/ai/ask',        // Required - SSE streaming endpoint
-    quota: '/api/ai/quota',    // Optional - quota endpoint
-    uploadFile: '/api/ai/upload', // Optional - file upload
-  },
-  getAuthToken: () => localStorage.getItem('token'),
-})
-
+setupRestifyAi(app)
 app.mount('#app')
-\`\`\`
+```
+
+### 4. Add the Component
 
-\`\`\`vue
-<!-- App.vue -->
+```vue
 <template>
-  <AiChatDrawer v-model="showChat" />
-  <button @click="showChat = true">Open AI Chat</button>
+  <AiChatDrawer v-model="aiStore.showChat" top-offset="50px" />
 </template>
 
-<script setup>
-import { ref } from 'vue'
-import { AiChatDrawer } from '@doderasoftware/restify-ai'
+<script setup lang="ts">
+import { AiChatDrawer, useRestifyAiStore } from '@doderasoftware/restify-ai'
 
-const showChat = ref(false)
+const aiStore = useRestifyAiStore()
 </script>
-\`\`\`
+```
 
----
+### 5. Enable Keyboard Shortcut (Optional)
 
-## ⚙️ Plugin Configuration
+```typescript
+// In your layout or App.vue
+import { useAiDrawerShortcut } from '@doderasoftware/restify-ai'
 
-### Required Options
+useAiDrawerShortcut() // Enables Cmd/Ctrl+G to toggle
+```
 
-| Option | Type | Description |
-|--------|------|-------------|
-| \`endpoints.ask\` | \`string\` | SSE streaming endpoint |
-| \`getAuthToken\` | \`() => string \| Promise<string>\` | Auth token getter |
+## ⚙️ Configuration
 
-### API Configuration
+### Full Configuration Options
 
-\`\`\`typescript
-{
-  baseUrl: 'https://api.example.com',
-  endpoints: {
-    ask: '/api/ai/ask',
-    quota: '/api/ai/quota',
-    uploadFile: '/api/ai/upload',
-  },
-  getAuthToken: () => authStore.token,
-  getCustomHeaders: () => ({
-    'X-CSRF-TOKEN': csrfToken,
-    'X-App-Version': '1.0.0',
-  }),
-}
-\`\`\`
+```typescript
+import type { App } from 'vue'
+import { RestifyAiPlugin } from '@doderasoftware/restify-ai'
+import type { MentionProvider, SuggestionProvider, AISuggestion } from '@doderasoftware/restify-ai'
+
+export function setupRestifyAi(app: App) {
+  app.use(RestifyAiPlugin, {
+    // ═══════════════════════════════════════════════════════════════
+    // REQUIRED
+    // ═══════════════════════════════════════════════════════════════
+    
+    endpoints: {
+      ask: '/ask',                    // SSE streaming endpoint
+      uploadFile: '/ai/upload',       // File upload endpoint
+      quota: '/ai/quota',             // Quota fetch endpoint
+    },
+    getAuthToken: () => localStorage.getItem('token'),
+
+    // ═══════════════════════════════════════════════════════════════
+    // API CONFIGURATION
+    // ═══════════════════════════════════════════════════════════════
+    
+    baseUrl: 'https://api.example.com',
+    
+    // Custom headers for every request
+    getCustomHeaders: () => ({
+      'X-Tenant-ID': getTenantId(),
+      'Accept-Language': getCurrentLocale(),
+    }),
+    
+    // Transform request payload before sending
+    buildRequest: (payload) => ({
+      ...payload,
+      customField: 'value',
+    }),
+    
+    // Parse SSE stream content (default handles OpenAI format)
+    parseStreamContent: (data) => {
+      const parsed = JSON.parse(data)
+      return parsed.choices?.[0]?.delta?.content || null
+    },
 
-### Request Customization
+    // ═══════════════════════════════════════════════════════════════
+    // RETRY CONFIGURATION
+    // ═══════════════════════════════════════════════════════════════
+    
+    retry: {
+      maxRetries: 3,
+      retryDelay: 1000,
+      shouldRetry: (error, attempt) => attempt < 3,
+    },
 
-\`\`\`typescript
-{
-  // Modify request payload before sending
-  buildRequest: (payload) => ({
-    ...payload,
-    context: { page: 'dashboard' },
-  }),
-  
-  // Custom stream parser (default: OpenAI format)
-  parseStreamContent: (data) => JSON.parse(data).content,
-  
-  // Request/response interceptors
-  requestInterceptor: (url, options) => options,
-  responseInterceptor: (response) => response,
-}
-\`\`\`
+    // ═══════════════════════════════════════════════════════════════
+    // INTERNATIONALIZATION
+    // ═══════════════════════════════════════════════════════════════
+    
+    // Translate function for i18n integration
+    translate: (key, params) => i18n.t(key, params),
+    
+    // Permission check function
+    can: (permission) => userCan(permission),
+
+    // ═══════════════════════════════════════════════════════════════
+    // LABELS (all customizable)
+    // ═══════════════════════════════════════════════════════════════
+    
+    labels: {
+      title: 'AI Assistant',
+      aiName: 'AI Assistant',
+      you: 'You',
+      newChat: 'New chat',
+      placeholder: 'Ask me anything...',
+      inputPlaceholder: 'Ask me anything...',
+      supportPlaceholder: 'Describe your issue...',
+      loadingText: 'Gathering data...',
+      analyzingText: 'Analyzing...',
+      craftingText: 'Crafting response...',
+      quotaRemaining: 'questions remaining',
+      noQuota: 'No AI credit available',
+      contactSupport: 'Contact Support',
+      close: 'Close',
+      minimize: 'Minimize',
+      fullscreen: 'Fullscreen',
+      exitFullscreen: 'Exit fullscreen',
+      copyToClipboard: 'Copy to clipboard',
+      copied: 'Content copied to clipboard',
+      showMore: 'Show more',
+      showLess: 'Show less',
+      retry: 'Retry',
+      attachFiles: 'Attach files',
+      emptyStateTitle: 'How can I help you today?',
+      emptyStateDescription: 'Ask questions or get help with tasks',
+      keyboardShortcutHint: 'Press ⌘G to toggle',
+      sendMessage: 'Send message',
+      attachFile: 'Attach file',
+      closeConfirmTitle: 'Close chat window?',
+      closeConfirmMessage: 'You will lose the conversation.',
+      confirmClose: 'Yes, close it',
+      cancel: 'Cancel',
+      toggleSupportMode: 'Contact Support',
+      exitSupportMode: 'Exit Support Mode',
+      historyLimitReachedTitle: 'Conversation Limit Reached',
+      historyLimitReachedMessage: 'Maximum messages reached.',
+      startNewChat: 'New Chat',
+    },
 
-### Retry Configuration
+    // ═══════════════════════════════════════════════════════════════
+    // MENTION PROVIDERS
+    // ═══════════════════════════════════════════════════════════════
+    
+    mentionProviders: createMentionProviders(),
+
+    // ═══════════════════════════════════════════════════════════════
+    // SUGGESTION PROVIDERS
+    // ═══════════════════════════════════════════════════════════════
+    
+    suggestionProviders: createSuggestionProviders(),
+    defaultSuggestions: getDefaultSuggestions(),
+
+    // ═══════════════════════════════════════════════════════════════
+    // THEME
+    // ═══════════════════════════════════════════════════════════════
+    
+    theme: {
+      primaryColor: '#3b82f6',
+      primaryLightColor: '#60a5fa',
+      userBubbleColor: '#3b82f6',
+      userTextColor: '#ffffff',
+      borderColor: '#e5e7eb',
+      drawerWidth: '600px',
+      drawerFullscreenWidth: '90vw',
+    },
 
-\`\`\`typescript
-{
-  retry: {
-    maxRetries: 3,
-    retryDelay: 1000, // ms, multiplied by attempt
-    shouldRetry: (error, attempt) => error.status >= 500,
-  },
+    // ═══════════════════════════════════════════════════════════════
+    // LIMITS
+    // ═══════════════════════════════════════════════════════════════
+    
+    chatHistoryLimit: 20,  // Maximum user messages per conversation
+    maxAttachments: 5,
+    maxFileSize: 10 * 1024 * 1024, // 10MB
+    acceptedFileTypes: 'image/*,.pdf,.txt,.doc,.docx,.xls,.xlsx,.csv',
+
+    // ═══════════════════════════════════════════════════════════════
+    // STORAGE
+    // ═══════════════════════════════════════════════════════════════
+    
+    chatHistoryKey: 'app_chat_history',
+    drawerStateKey: 'app_chat_drawer_open',
+
+    // ═══════════════════════════════════════════════════════════════
+    // FEATURES
+    // ═══════════════════════════════════════════════════════════════
+    
+    keyboardShortcut: 'mod+g',  // 'mod' = Cmd on Mac, Ctrl on Windows
+    enableSupportMode: true,
+    canToggle: () => true,
+
+    // ═══════════════════════════════════════════════════════════════
+    // AVATARS
+    // ═══════════════════════════════════════════════════════════════
+    
+    assistantAvatar: CustomAiAvatarComponent,
+    userAvatar: () => authStore.profile?.avatar || null,
+
+    // ═══════════════════════════════════════════════════════════════
+    // CALLBACKS
+    // ═══════════════════════════════════════════════════════════════
+    
+    onError: (error) => console.error('AI Error:', error),
+    onQuotaFetched: (quota) => console.log('Quota:', quota),
+    onMessageSent: (message) => analytics.track('ai_message_sent'),
+    onResponseReceived: (message) => console.log('Response:', message),
+    onDrawerToggle: (isOpen) => console.log('Drawer:', isOpen),
+    onNewChat: () => console.log('New chat started'),
+    
+    // Stream lifecycle hooks
+    onStreamStart: () => console.log('Stream started'),
+    onStreamEnd: (fullMessage) => console.log('Stream ended'),
+    onStreamChunk: (chunk) => console.log('Chunk:', chunk),
+    beforeSend: (payload) => payload,
+    afterResponse: (message) => {},
+
+    // File upload hooks
+    onFileUploadStart: (file) => {},
+    onFileUploadProgress: (file, progress) => {},
+    onFileUploadComplete: (file) => {},
+    onFileUploadError: (file, error) => {},
+  })
 }
-\`\`\`
+```
 
-### Providers
+## 📋 AiChatDrawer Props
 
-\`\`\`typescript
-{
-  // @Mention providers
-  mentionProviders: [
-    {
-      type: 'employee',
-      label: 'Employees',
-      priority: 10,
-      search: async (query) => api.searchEmployees(query),
-    },
-  ],
-  
-  // Route-aware suggestions
-  suggestionProviders: [
-    {
-      id: 'dashboard',
-      routes: ['/dashboard', '/analytics'],
-      getSuggestions: (context) => [...],
-    },
-  ],
-  
-  // Default suggestions for empty state
-  defaultSuggestions: [
-    { id: '1', title: 'How can you help?', prompt: 'What can you do?' },
-  ],
-}
-\`\`\`
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `boolean` | required | Controls drawer visibility (v-model) |
+| `width` | `string` | `"600px"` | Drawer width |
+| `fullscreenWidth` | `string` | `"90vw"` | Width when in fullscreen mode |
+| `topOffset` | `string` | `"0"` | Top offset for fixed headers |
+| `position` | `"left" \| "right"` | `"right"` | Drawer position |
+| `showBackdrop` | `boolean` | `false` | Show backdrop overlay |
+| `closeOnBackdropClick` | `boolean` | `false` | Close when clicking backdrop |
+| `closeOnEscape` | `boolean` | `true` | Close on Escape key |
+| `showQuota` | `boolean` | `true` | Show quota display (API usage remaining) |
+| `showMessageCount` | `boolean` | `true` | Show message count badge (X/20 format) |
+| `showFullscreenToggle` | `boolean` | `true` | Show fullscreen button |
+| `showMinimizeButton` | `boolean` | `true` | Show minimize button |
+| `showCloseButton` | `boolean` | `true` | Show close button |
+| `showNewChatButton` | `boolean` | `true` | Show new chat button |
+| `confirmClose` | `boolean` | `true` | Confirm before clearing history |
+| `autoFetchQuota` | `boolean` | `true` | Auto-fetch quota when opened |
+| `historyLimit` | `HistoryLimitConfig` | - | History limit configuration |
+| `loadingText` | `LoadingTextConfig` | - | Loading text configuration |
+| `ui` | `AiChatDrawerUI` | `{}` | Custom CSS classes |
+| `texts` | `AiChatDrawerTexts` | `{}` | Custom text labels |
+
+### Component Usage Example
+
+```vue
+<template>
+  <AiChatDrawer
+    v-model="aiStore.showChat"
+    top-offset="50px"
+    :show-backdrop="false"
+    :confirm-close="true"
+    :show-quota="true"
+    @contact-support="handleContactSupport"
+  >
+    <template #context-link>
+      <p class="text-center text-xs text-gray-500">
+        For accurate results, provide
+        <router-link to="/settings/ai-context" class="text-primary-600 hover:underline">
+          company context
+        </router-link>
+      </p>
+    </template>
+  </AiChatDrawer>
+</template>
 
-### Limits & Storage
+<script setup lang="ts">
+import { AiChatDrawer, useRestifyAiStore, useAiDrawerShortcut } from '@doderasoftware/restify-ai'
 
-\`\`\`typescript
-{
-  chatHistoryLimit: 15,           // Max messages
-  maxAttachments: 5,              // Max files per message
-  maxFileSize: 10 * 1024 * 1024,  // 10MB
-  acceptedFileTypes: 'image/*,.pdf,.txt',
-  chatHistoryKey: 'my_chat_history',    // sessionStorage key
-  drawerStateKey: 'my_drawer_state',    // localStorage key
-}
-\`\`\`
+const aiStore = useRestifyAiStore()
 
-### Features
+useAiDrawerShortcut()
 
-\`\`\`typescript
-{
-  keyboardShortcut: 'cmd+g',    // null to disable
-  enableSupportMode: true,      // Support request toggle
+function handleContactSupport() {
+  // Handle support request
 }
-\`\`\`
+</script>
+```
 
-### Custom Components
+## 📡 Events
 
-\`\`\`typescript
-{
-  assistantAvatar: MyAvatarComponent,
-  userAvatar: UserAvatarComponent,
-}
-\`\`\`
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `boolean` | Drawer state changed |
+| `close` | - | Drawer was closed |
+| `contact-support` | - | Support mode activated |
+| `new-chat` | - | New chat started |
 
-### Lifecycle Callbacks
+## 🎰 Slots
 
-\`\`\`typescript
-{
-  onError: (error) => console.error(error),
-  onQuotaFetched: (quota) => console.log(quota),
-  onMessageSent: (message) => analytics.track('message_sent'),
-  onResponseReceived: (message) => console.log(message),
-  onDrawerToggle: (isOpen) => console.log(isOpen),
-  onNewChat: () => console.log('New chat started'),
-  
-  // Stream hooks
-  onStreamStart: () => console.log('Streaming...'),
-  onStreamEnd: (fullMessage) => console.log('Done'),
-  onStreamChunk: (chunk) => console.log(chunk.content),
-  beforeSend: (payload) => payload,
-  afterResponse: (message) => saveToHistory(message),
-  
-  // File upload hooks
-  onFileUploadStart: (file) => console.log('Uploading', file.name),
-  onFileUploadProgress: (file, progress) => console.log(progress),
-  onFileUploadComplete: (file) => console.log('Done'),
-  onFileUploadError: (file, error) => console.error(error),
+| Slot | Props | Description |
+|------|-------|-------------|
+| `header` | `HeaderSlotProps` | Custom header content |
+| `quota` | `{ quota: ChatQuota }` | Custom quota display |
+| `setup` | - | Custom setup guide |
+| `empty-state` | `{ suggestions, onClick }` | Custom empty state |
+| `message` | `MessageSlotProps` | Custom message bubble |
+| `input` | `InputSlotProps` | Custom input area |
+| `context-link` | - | Custom context link below input |
+
+### Slot Props Types
+
+```typescript
+interface HeaderSlotProps {
+  quota: ChatQuota
+  isFullscreen: boolean
+  hasHistory: boolean
+  onNewChat: () => void
+  onClose: () => void
+  onMinimize: () => void
+  onToggleFullscreen: () => void
 }
-\`\`\`
 
-### Labels / i18n
+interface MessageSlotProps {
+  message: ChatMessage
+  isUser: boolean
+  isLoading: boolean
+  isStreaming: boolean
+}
 
-\`\`\`typescript
-{
-  labels: {
-    aiName: 'My AI Assistant',
-    inputPlaceholder: 'Type your message...',
-    emptyStateTitle: 'How can I help?',
-    // 40+ customizable labels
-  },
-  translate: (key, params) => i18n.t(key, params),
-  can: (permission) => user.hasPermission(permission),
+interface InputSlotProps {
+  modelValue: string
+  sending: boolean
+  disabled: boolean
+  onSubmit: (payload: SubmitPayload) => void
+  onCancel: () => void
 }
-\`\`\`
+```
 
----
+## 🏪 Store API
 
-## 🧩 Components
+```typescript
+import { useRestifyAiStore } from '@doderasoftware/restify-ai'
 
-### \`<AiChatDrawer>\`
+const store = useRestifyAiStore()
 
-Main chat drawer component with all features.
+// ═══════════════════════════════════════════════════════════════
+// STATE
+// ═══════════════════════════════════════════════════════════════
+
+store.chatHistory         // ChatMessage[] - All messages
+store.showChat            // boolean - Drawer visibility
+store.sending             // boolean - Message being sent
+store.loading             // boolean - Loading state
+store.isFullscreen        // boolean - Fullscreen mode
+store.quota               // { limit, used, remaining }
+store.error               // { message, failedQuestion, failedAttachments, timestamp }
+store.supportRequestMode  // boolean - Support mode active
+store.pageContext         // PageContext | null - Current page context
+
+// ═══════════════════════════════════════════════════════════════
+// GETTERS
+// ═══════════════════════════════════════════════════════════════
+
+store.hasMessages         // boolean - Has any messages
+store.isInSetupMode       // boolean - In setup mode
+store.canChat             // boolean - Can send messages
+
+// ═══════════════════════════════════════════════════════════════
+// ACTIONS
+// ═══════════════════════════════════════════════════════════════
+
+store.toggleDrawer()            // Toggle drawer visibility
+store.openDrawer()              // Open drawer
+store.closeDrawer()             // Close drawer
+store.askQuestion(question, attachments?, mentions?, isSupportRequest?)
+store.cancelRequest()           // Cancel current request
+store.retry()                   // Retry failed message
+store.clearChatHistory()        // Clear all messages
+store.clearError()              // Clear error state
+store.toggleSupportMode()       // Toggle support mode
+store.fetchQuota()              // Fetch quota from server
+store.uploadFile(file)          // Upload file
+store.setPageContext(context)   // Set page context
+store.scrollToBottom()          // Scroll chat to bottom
+```
+
+## 🪝 Composables
+
+### useAiDrawerShortcut
+
+Toggle drawer with keyboard shortcut:
+
+```typescript
+import { useAiDrawerShortcut } from '@doderasoftware/restify-ai'
+
+// Uses store's showChat state directly
+useAiDrawerShortcut()
+```
+
+### usePageAiContext
+
+Set page context for AI suggestions:
+
+```typescript
+import { usePageAiContext } from '@doderasoftware/restify-ai'
+
+// Simple usage
+usePageAiContext('invoices')
+
+// With dynamic metadata
+usePageAiContext('employee-detail', {
+  employeeId: computed(() => route.params.id),
+  employeeName: computed(() => employee.value?.name),
+})
+```
 
-#### Props
+### useAiContext
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| \`v-model\` | \`boolean\` | - | Drawer visibility |
-| \`width\` | \`string\` | \`'600px'\` | Drawer width |
-| \`fullscreenWidth\` | \`string\` | \`'90vw'\` | Fullscreen width |
-| \`position\` | \`'left' \| 'right'\` | \`'right'\` | Drawer position |
-| \`showBackdrop\` | \`boolean\` | \`false\` | Show backdrop overlay |
-| \`closeOnBackdropClick\` | \`boolean\` | \`false\` | Close on backdrop click |
-| \`closeOnEscape\` | \`boolean\` | \`true\` | Close on Escape key |
-| \`showQuota\` | \`boolean\` | \`true\` | Show quota display |
-| \`showFullscreenToggle\` | \`boolean\` | \`true\` | Show fullscreen button |
-| \`showMinimizeButton\` | \`boolean\` | \`true\` | Show minimize button |
-| \`showCloseButton\` | \`boolean\` | \`true\` | Show close button |
-| \`showNewChatButton\` | \`boolean\` | \`true\` | Show new chat button |
-| \`confirmClose\` | \`boolean\` | \`true\` | Confirm before closing |
-| \`ui\` | \`AiChatDrawerUI\` | - | Custom CSS classes |
-| \`texts\` | \`AiChatDrawerTexts\` | - | Custom text labels |
-| \`historyLimit\` | \`HistoryLimitConfig\` | - | History limit config |
-| \`loadingText\` | \`LoadingTextConfig\` | - | Dynamic loading text |
-
-#### Events
+Programmatic context control:
 
-| Event | Payload | Description |
-|-------|---------|-------------|
-| \`close\` | - | Drawer closed |
-| \`contact-support\` | - | Support mode triggered |
-| \`new-chat\` | - | New chat started |
+```typescript
+import { useAiContext } from '@doderasoftware/restify-ai'
 
-#### Slots
+const { setContext, updateContext, clearContext, context } = useAiContext()
 
-| Slot | Props | Description |
-|------|-------|-------------|
-| \`header\` | \`HeaderSlotProps\` | Custom header |
-| \`empty-state\` | \`{ suggestions, onClick }\` | Custom empty state |
-| \`message\` | \`MessageSlotProps\` | Custom message rendering |
-| \`input\` | \`InputSlotProps\` | Custom input |
-| \`quota\` | \`{ quota }\` | Custom quota display |
-| \`setup\` | - | Custom setup guide |
-| \`context-link\` | - | Link above input |
-
-### Other Components
-
-| Component | Description |
-|-----------|-------------|
-| \`<ChatInput>\` | Message input with attachments & mentions |
-| \`<ChatMessage>\` | Single message display |
-| \`<AiEmptyState>\` | Empty state with suggestions |
-| \`<MentionList>\` | @mention dropdown |
-| \`<AiAvatar>\` | AI avatar icon |
-| \`<UserAvatar>\` | User avatar icon |
-| \`<ChatMessageActions>\` | Copy/action buttons |
-
-All components accept \`:ui\` and \`:texts\` props for full customization.
+setContext({
+  pageType: 'dashboard',
+  entityType: 'report',
+  entityId: '123',
+  metadata: { period: 'Q4' }
+})
+```
 
----
+### useAiSuggestions
 
-## 🎨 UI Customization
+Get suggestions for current context:
 
-Every component accepts a \`:ui\` prop for CSS class overrides:
+```typescript
+import { useAiSuggestions } from '@doderasoftware/restify-ai'
 
-\`\`\`vue
-<AiChatDrawer
-  :ui="{
-    drawer: 'my-drawer-class',
-    header: 'my-header-class',
-    body: 'my-body-class',
-  }"
-  :texts="{
-    title: 'My AI',
-    placeholder: 'Ask anything...',
-  }"
-/>
-\`\`\`
+const { suggestions, resolvePrompt } = useAiSuggestions()
+```
 
-### Available UI Props
+## 🏷️ Mention Providers
 
-- \`AiChatDrawerUI\` - backdrop, drawer, panel, header, body, etc.
-- \`ChatInputUI\` - root, textarea, sendButton, attachButton, etc.
-- \`ChatMessageUI\` - userBubble, assistantBubble, loadingDots, etc.
-- \`AiEmptyStateUI\` - grid, suggestionCard, title, etc.
-- \`MentionListUI\` - item, itemSelected, groupHeader, etc.
+Enable @mentions to reference entities from your application:
 
----
+```typescript
+import type { MentionProvider, MentionItem } from '@doderasoftware/restify-ai'
 
-## 📚 Composables
-
-\`\`\`typescript
-import {
-  useRestifyAiStore,      // Pinia store
-  useAiSuggestions,       // Suggestions management
-  useAiContext,           // Page context
-  usePageAiContext,       // Route-based context
-  useKeyboardShortcut,    // Custom shortcuts
-  useAiDrawerShortcut,    // Drawer toggle shortcut
-  useMentionParsing,      // Parse @mentions
-  useChatMarkdown,        // Markdown rendering
-  useChatScroll,          // Auto-scroll
-  useChatErrorHandling,   // Error management
-  useLoadingText,         // Dynamic loading messages
-  useHistoryLimit,        // History limit dialogs
-} from '@doderasoftware/restify-ai'
-\`\`\`
+function createMentionProviders(): MentionProvider[] {
+  return [
+    {
+      type: 'employee',
+      label: 'Team Members',
+      iconClass: 'text-primary',
+      priority: 10,
+      
+      // Search function - can be sync or async
+      search: (query: string): MentionItem[] => {
+        const employeeStore = useEmployeeStore()
+        const employees = employeeStore.allEmployees || []
+
+        if (!query) {
+          return employees.slice(0, 5).map(emp => ({
+            id: emp.id,
+            type: 'employee',
+            attributes: emp.attributes,
+          }))
+        }
+
+        const lowerQuery = query.toLowerCase()
+        return employees
+          .filter((emp) => {
+            const firstName = emp.attributes?.first_name?.toLowerCase() || ''
+            const lastName = emp.attributes?.last_name?.toLowerCase() || ''
+            return firstName.includes(lowerQuery) || lastName.includes(lowerQuery)
+          })
+          .slice(0, 5)
+          .map(emp => ({
+            id: emp.id,
+            type: 'employee',
+            attributes: emp.attributes,
+          }))
+      },
+      
+      // Display formatting
+      getDisplayName: (item: MentionItem): string => {
+        const firstName = item.attributes?.first_name || ''
+        const lastName = item.attributes?.last_name || ''
+        return `${firstName} ${lastName}`.trim()
+      },
+      
+      getSubtitle: (item: MentionItem): string | null => {
+        return item.attributes?.position || null
+      },
+      
+      buildMentionText: (item: MentionItem): string => {
+        const firstName = item.attributes?.first_name || ''
+        const lastName = item.attributes?.last_name || ''
+        return `@${firstName} ${lastName}`.trim()
+      },
+    },
+    {
+      type: 'job',
+      label: 'Jobs',
+      iconClass: 'text-blue-500',
+      routes: ['/hiring/jobs'],  // Only show on these routes
+      priority: 5,
+      search: async (query: string): Promise<MentionItem[]> => {
+        const response = await api.get('/jobs', { params: { search: query }})
+        return response.data.map(job => ({
+          id: job.id,
+          type: 'job',
+          attributes: job,
+        }))
+      },
+      getDisplayName: (item) => item.attributes?.title || 'Untitled',
+      getSubtitle: (item) => item.attributes?.location || null,
+    },
+  ]
+}
+```
+
+### MentionProvider Interface
+
+```typescript
+interface MentionProvider {
+  type: string                                              // Unique type identifier
+  label: string                                             // Display label for group
+  icon?: Component                                          // Icon component
+  iconClass?: string                                        // Icon CSS classes
+  routes?: string[]                                         // Limit to specific routes
+  priority?: number                                         // Sort order (higher = first)
+  search: (query: string) => Promise<MentionItem[]> | MentionItem[]
+  getDisplayName?: (item: MentionItem) => string
+  getSubtitle?: (item: MentionItem) => string | null
+  buildMentionText?: (item: MentionItem) => string
+}
+
+interface MentionItem {
+  id: string
+  type: string
+  name?: string
+  label?: string
+  title?: string
+  attributes?: Record<string, any> | null
+  relationships?: Record<string, any> | null
+}
+```
 
-### Store Actions
+## 💡 Suggestion Providers
 
-\`\`\`typescript
-const store = useRestifyAiStore()
+Context-aware suggestions based on current page:
 
-store.askQuestion(question, attachments, mentions)
-store.cancelRequest()
-store.retry()
-store.clearChatHistory()
-store.clearError()
-store.fetchQuota()
-store.toggleSupportMode()
-\`\`\`
-
-### Store State
-
-\`\`\`typescript
-store.chatHistory      // ChatMessage[]
-store.sending          // boolean
-store.error            // ChatError
-store.quota            // ChatQuota
-store.showChat         // boolean
-store.isFullscreen     // boolean
-store.supportRequestMode // boolean
-\`\`\`
+```typescript
+import type { SuggestionProvider, AISuggestion, PageContext } from '@doderasoftware/restify-ai'
+import { UserGroupIcon, ChartBarIcon, CalendarDaysIcon } from '@heroicons/vue/24/outline'
 
----
+function createSuggestionProviders(): SuggestionProvider[] {
+  return [
+    {
+      id: 'employees',
+      routes: ['/employees'],
+      priority: 10,
+      
+      getSuggestions: (context: PageContext): AISuggestion[] => {
+        const isDetailView = context.entityId
+        const employeeName = context.metadata?.employeeName
+
+        if (isDetailView && employeeName) {
+          // Suggestions for employee detail page
+          return [
+            {
+              id: 'performance-review',
+              title: 'Prepare Evaluation',
+              description: 'Performance review points',
+              icon: ChartBarIcon,
+              gradientClass: 'bg-gradient-to-br from-violet-500/10 to-purple-500/10',
+              prompt: `Help me prepare a performance review for ${employeeName}.`,
+              permission: 'manageEmployees',
+            },
+          ]
+        }
+
+        // Suggestions for employee list
+        return [
+          {
+            id: 'find-available',
+            title: 'Who is Available?',
+            description: 'See who is not on leave',
+            icon: CalendarDaysIcon,
+            gradientClass: 'bg-gradient-to-br from-teal-500/10 to-emerald-500/10',
+            prompt: 'Who is available today and not on leave?',
+            permission: 'manageEmployees',
+          },
+          {
+            id: 'team-analytics',
+            title: 'Team Analysis',
+            description: 'Team structure insights',
+            icon: ChartBarIcon,
+            gradientClass: 'bg-gradient-to-br from-amber-500/10 to-orange-500/10',
+            prompt: 'Give me an overview of our team structure.',
+            permission: 'manageEmployees',
+          },
+        ]
+      },
+    },
+    {
+      id: 'hiring',
+      routes: ['/hiring/jobs', '/hiring/candidates'],
+      priority: 10,
+      getSuggestions: (): AISuggestion[] => [
+        {
+          id: 'open-positions',
+          title: 'Open Positions',
+          description: 'List all open job positions',
+          icon: UserGroupIcon,
+          prompt: 'Show me all currently open job positions.',
+        },
+      ],
+    },
+  ]
+}
+```
 
-## 🔧 Advanced Features
+### Default Suggestions
 
-### History Limit Dialog
+```typescript
+function getDefaultSuggestions(): AISuggestion[] {
+  return [
+    {
+      id: 'help',
+      title: 'How can you help?',
+      description: 'Learn what I can do',
+      prompt: 'What can you help me with?',
+    },
+    {
+      id: 'contact-support',
+      title: 'Contact Support',
+      description: 'Get help from a human',
+      prompt: 'I need to contact support',
+      isSupportRequest: true,
+    },
+  ]
+}
+```
+
+### SuggestionProvider Interface
+
+```typescript
+interface SuggestionProvider {
+  id: string                                                  // Unique identifier
+  routes?: string[]                                           // Route patterns to match
+  matcher?: (path: string, context: PageContext | null) => boolean
+  getSuggestions: (context: PageContext) => AISuggestion[]
+  extractContext?: (path: string) => Record<string, any>
+  priority?: number                                           // Higher = first
+}
 
-\`\`\`vue
-<AiChatDrawer
-  :history-limit="{
-    limit: 20,
-    showWarningAt: 3,
-    warningMessage: 'Almost at limit!',
-    limitMessage: 'Start a new chat to continue.',
-  }"
-/>
-\`\`\`
+interface AISuggestion {
+  id: string
+  title: string
+  description?: string
+  icon?: Component
+  className?: string
+  gradientClass?: string
+  prompt: string | ((context: PageContext) => string)
+  permission?: string
+  category?: string
+  isSupportRequest?: boolean
+}
+```
+
+## 🎨 UI Customization
 
-### Dynamic Loading Text
+Override CSS classes for any component:
 
-\`\`\`vue
+```vue
 <AiChatDrawer
-  :loading-text="{
-    messages: ['Thinking...', 'Analyzing...', 'Almost done...'],
-    intervals: [0, 2000, 4000],
+  v-model="isOpen"
+  :ui="{
+    backdrop: 'bg-black/50 backdrop-blur-sm',
+    drawer: 'shadow-2xl',
+    panel: 'bg-gray-50 dark:bg-gray-900',
+    header: 'border-b-2 border-primary-500',
+    body: 'custom-scrollbar',
+    footer: 'border-t border-gray-200',
   }"
 />
-\`\`\`
-
-### Keyboard Shortcut
-
-\`\`\`typescript
-// Plugin config
-{ keyboardShortcut: 'cmd+shift+a' }
-
-// Or use composable
-const { toggle } = useAiDrawerShortcut()
-\`\`\`
-
----
-
-## 📡 Laravel Restify Backend
-
-Expected SSE endpoint format:
-
-\`\`\`php
-// routes/api.php
-Route::post('/ai/ask', [AiController::class, 'ask']);
-Route::get('/ai/quota', [AiController::class, 'quota']);
-\`\`\`
-
-\`\`\`php
-// AiController.php
-public function ask(Request $request)
-{
-    return response()->stream(function () use ($request) {
-        // Stream OpenAI-format chunks
-        echo "data: " . json_encode([
-            'choices' => [['delta' => ['content' => 'Hello']]]
-        ]) . "\n\n";
-        ob_flush();
-        flush();
-        
-        echo "data: [DONE]\n\n";
-    }, 200, [
-        'Content-Type' => 'text/event-stream',
-        'Cache-Control' => 'no-cache',
-        'X-Accel-Buffering' => 'no',
-    ]);
+```
+
+### AiChatDrawerUI
+
+```typescript
+interface AiChatDrawerUI {
+  backdrop?: string              // Backdrop overlay
+  drawer?: string                // Main drawer container
+  panel?: string                 // Inner panel
+  header?: string                // Header container
+  headerTitle?: string           // Header title
+  headerActions?: string         // Header actions
+  headerActionButton?: string    // Header buttons
+  body?: string                  // Messages container
+  footer?: string                // Footer container
+  quotaDisplay?: string          // Quota display
+  messageCountBadge?: string     // Message count badge
+  newChatButton?: string         // New chat button
+  errorContainer?: string        // Error container
+  errorMessage?: string          // Error message
+  retryButton?: string           // Retry button
+  closeConfirmModal?: string     // Confirm modal
+  closeConfirmButton?: string    // Confirm button
+  cancelButton?: string          // Cancel button
+  historyLimitModal?: string     // History limit modal
+  historyLimitButton?: string    // History limit button
 }
-\`\`\`
-
----
+```
+
+### ChatInputUI
+
+```typescript
+interface ChatInputUI {
+  root?: string                  // Root container
+  form?: string                  // Form wrapper
+  inputContainer?: string        // Input container
+  inputWrapper?: string          // Input border wrapper
+  textarea?: string              // Textarea element
+  attachButton?: string          // Attach button
+  sendButton?: string            // Send button
+  sendButtonActive?: string      // Send active state
+  sendButtonDisabled?: string    // Send disabled state
+  stopButton?: string            // Stop button
+  supportToggle?: string         // Support toggle
+  supportBadge?: string          // Support badge
+  attachmentsContainer?: string  // Attachments container
+  attachmentItem?: string        // Attachment item
+  attachmentThumbnail?: string   // Attachment thumbnail
+  attachmentRemove?: string      // Remove button
+  suggestionsDropdown?: string   // Suggestions dropdown
+  suggestionItem?: string        // Suggestion item
+  suggestionItemSelected?: string // Selected suggestion
+  contextLink?: string           // Context link
+}
+```
+
+### ChatMessageUI
+
+```typescript
+interface ChatMessageUI {
+  root?: string                  // Root container
+  userMessage?: string           // User message container
+  userBubble?: string            // User bubble
+  userAvatar?: string            // User avatar
+  assistantMessage?: string      // Assistant container
+  assistantBubble?: string       // Assistant bubble
+  loadingIndicator?: string      // Loading indicator
+  loadingDots?: string           // Loading dots
+  content?: string               // Content wrapper
+  attachmentsContainer?: string  // Attachments
+  attachmentItem?: string        // Attachment item
+  actionsContainer?: string      // Actions container
+  showMoreButton?: string        // Show more button
+}
+```
 
 ## 📝 TypeScript Types
 
 All types are exported:
 
-\`\`\`typescript
+```typescript
 import type {
+  // Core Config
+  RestifyAiConfig,
+  RestifyAiEndpoints,
+  RestifyAiLabels,
+  RestifyAiTheme,
+  
+  // Chat Types
   ChatMessage,
+  ChatQuota,
+  ChatError,
   ChatAttachment,
-  Mention,
+  ChatRole,
+  SubmitPayload,
+  
+  // Context
+  PageContext,
+  
+  // Providers
   MentionProvider,
+  MentionItem,
+  Mention,
   SuggestionProvider,
   AISuggestion,
-  RestifyAiConfig,
-  ChatQuota,
-  ChatError,
-  // UI types
+  
+  // History
+  HistoryLimitConfig,
+  LoadingTextConfig,
+  
+  // UI Customization
   AiChatDrawerUI,
   ChatInputUI,
   ChatMessageUI,
-  // Text types
+  AiEmptyStateUI,
+  MentionListUI,
+  
+  // Text Customization
   AiChatDrawerTexts,
   ChatInputTexts,
-  // Config types
-  HistoryLimitConfig,
-  LoadingTextConfig,
-  RetryConfig,
-  // Hook types
+  ChatMessageTexts,
+  
+  // Slot Props
+  HeaderSlotProps,
+  MessageSlotProps,
+  InputSlotProps,
+  EmptyStateSlotProps,
+  
+  // Hooks
   BeforeSendHook,
   AfterResponseHook,
+  OnStreamStartHook,
+  OnStreamEndHook,
+  OnStreamChunkHook,
   StreamParserFunction,
+  RetryConfig,
 } from '@doderasoftware/restify-ai'
-\`\`\`
+```
 
----
+## 🔌 Backend Integration
 
-## 📋 Quick Reference
-
-| Feature | Configuration |
-|---------|---------------|
-| SSE Streaming | Built-in, automatic |
-| Keyboard Shortcut | \`keyboardShortcut: 'cmd+g'\` |
-| @Mentions | \`mentionProviders: [...]\` |
-| Route Suggestions | \`suggestionProviders: [...]\` |
-| File Attachments | \`endpoints.uploadFile\` + \`maxAttachments\` |
-| Support Mode | \`enableSupportMode: true\` |
-| Custom Headers | \`getCustomHeaders: () => ({...})\` |
-| Auth Token | \`getAuthToken: () => token\` |
-| Base URL | \`baseUrl: 'https://api.example.com'\` |
-| Error Handling | \`onError: (err) => {...}\` |
-| Retry Logic | \`retry: { maxRetries: 3 }\` |
-| UI Customization | \`:ui\` prop on all components |
-| Text/i18n | \`:texts\` prop + \`labels\` config |
-| History Limit | \`:history-limit\` prop |
-| Loading Messages | \`:loading-text\` prop |
+This package is designed for [Laravel Restify](https://laravel-restify.com) backends:
 
----
+### Ask Endpoint (SSE Stream)
+
+```php
+// routes/api.php
+Route::post('/ask', [AiController::class, 'ask']);
+```
+
+**Request:**
+```json
+{
+  "question": "Who is available today?",
+  "history": [
+    { "role": "user", "message": "Hello" },
+    { "role": "assistant", "message": "Hi! How can I help?" }
+  ],
+  "stream": true,
+  "files": [{ "id": "file-123", "name": "report.pdf" }],
+  "mentions": [{ "id": "emp-1", "type": "employee", "name": "John Doe" }],
+  "contact_support": false
+}
+```
+
+**Response (SSE):**
+```
+data: {"choices":[{"delta":{"content":"Based on"}}]}
+data: {"choices":[{"delta":{"content":" the schedule..."}}]}
+data: [DONE]
+```
+
+### Quota Endpoint
+
+```php
+// routes/api.php
+Route::get('/ai/quota', [AiController::class, 'quota']);
+```
+
+**Response:**
+```json
+{
+  "data": {
+    "limit": 100,
+    "used": 25,
+    "remaining": 75
+  }
+}
+```
+
+### Upload Endpoint
+
+```php
+// routes/api.php
+Route::post('/ai/upload', [AiController::class, 'upload']);
+```
+
+**Response:**
+```json
+{
+  "data": {
+    "id": "file-123",
+    "name": "document.pdf",
+    "url": "/storage/uploads/document.pdf",
+    "type": "application/pdf",
+    "size": 102400
+  }
+}
+```
+
+## ⌨️ Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `⌘/Ctrl + G` | Toggle drawer (configurable) |
+| `Escape` | Close drawer |
+| `Enter` | Send message |
+| `Shift + Enter` | New line |
+
+## 💾 Session Storage
+
+Chat history persists in `sessionStorage` by default:
+
+- Key: `restify_ai_chat_history` (configurable via `chatHistoryKey`)
+- Cleared on browser close
+- Persists across page navigation
+
+## 📦 Package Exports
+
+```typescript
+// Components
+export { AiChatDrawer } from './components'
+
+// Store
+export { useRestifyAiStore } from './store'
+
+// Composables
+export { 
+  useAiDrawerShortcut,
+  usePageAiContext,
+  useAiContext,
+  useAiSuggestions 
+} from './composables'
+
+// Config
+export { 
+  initRestifyAi, 
+  getConfig, 
+  getLabels, 
+  getUI,
+  RestifyAiPlugin 
+} from './config'
+
+// Types
+export * from './types'
+```
+
+## 🤝 Requirements
+
+- **Vue 3.3+**
+- **Pinia 2.1+**
+- A backend implementing the streaming chat API (e.g., [Laravel Restify](https://laravel-restify.com))
+
+## 🔗 Links
+
+- [📖 Laravel Restify Documentation](https://laravel-restify.com)
+- [📦 npm Package](https://www.npmjs.com/package/@doderasoftware/restify-ai)
+- [🏢 BinarCode](https://binarcode.com)
+- [💻 GitHub](https://github.com/BinarCode/laravel-restify)
 
 ## 📄 License
 
-MIT © [Dodera Software](https://github.com/doderasoftware)
+MIT © [BinarCode](https://binarcode.com)
+
+---
+
+Built with ❤️ by the [BinarCode](https://binarcode.com) team · Published by [Dodera Software](https://doderasoft.com)