docs: add AI-friendly documentation and code comments

Add comprehensive documentation for AI assistants:
- .cursorrules with project context and conventions
- ARCHITECTURE.md with technical details
- DEVELOPMENT.md with practical guides
- JSDoc comments in all JavaScript modules
- Update README.md with AI-Friendly Development section

This enables AI tools (Cursor, Claude Code, GitHub Copilot) to understand the project and generate code following CoreUI Vue patterns.

.cursorrules

@@ -0,0 +1,349 @@
+# CoreUI Free Vue Admin Template - AI Assistant Rules
+
+You are working with the CoreUI Free Vue Admin Template, a professional admin dashboard built with Vue 3, CoreUI Vue components, and modern build tools. This project uses Vite for development and building, Vue Router for navigation, Pinia for state management, and Sass for styling.
+
+## Critical Rules
+
+**Component Library**: ALWAYS use CoreUI Vue components from https://coreui.io/vue/docs/. NEVER use Tailwind CSS, Vuetify, Element Plus, or other component libraries. This project is built on Bootstrap 5 and CoreUI Vue components exclusively.
+
+**Technology Stack**: This project uses:
+- Vue 3.5.x with Composition API and script setup
+- Single File Components (SFC) with <template>, <script>, and <style> sections
+- CoreUI Vue 5.x and @coreui/coreui 5.x
+- Vue Router 5.x for client-side routing
+- Pinia 3.x for state management
+- Vite 8.x for development server and building
+- Sass/SCSS for styling with Bootstrap 5 variables
+- Chart.js 4.x with @coreui/vue-chartjs for data visualization
+
+## Code Conventions
+
+**Vue/JavaScript Standards**:
+- Use Composition API with `<script setup>` syntax
+- Use ref() and reactive() for reactive state
+- Follow Vue 3 Composition API patterns
+- Use Prettier formatting: no semicolons, single quotes, 2-space indentation
+- Enforce ESLint rules with Vue and Prettier plugins
+- Prefer const and arrow functions
+- Use destructuring where appropriate
+
+**File Organization**:
+- `src/` - All source code
+  - `components/` - Reusable UI components (AppHeader, AppSidebar, etc.)
+  - `views/` - Page components organized by feature (dashboard, forms, charts, etc.)
+  - `layouts/` - Layout wrapper components (DefaultLayout)
+  - `assets/` - Static assets (images, brand logos)
+  - `scss/` - Global styles and theme customization
+  - `router/` - Router configuration
+  - `stores/` - Pinia stores
+  - `_nav.js` - Navigation/sidebar menu configuration
+  - `App.vue` - Main application component
+  - `main.js` - Application entry point
+
+**Vue/SFC Practices**:
+- Use `<script setup>` for components (preferred modern syntax)
+- Use `defineProps()` and `defineEmits()` for component API
+- Use computed() for derived state
+- Use watch() or watchEffect() for side effects
+- Keep components focused and single-responsibility
+- Extract reusable logic into composables (useX pattern)
+- Use Suspense for async components when needed
+
+**CSS/Sass Practices**:
+- Import global styles in main.js: `import './scss/style.scss'`
+- Use Bootstrap utilities first before custom CSS
+- Leverage CoreUI CSS custom properties for theming
+- Support dark mode through CoreUI's color mode system
+- File: `src/scss/style.scss` - main stylesheet importing CoreUI and Bootstrap
+- File: `src/scss/_custom.scss` - custom style overrides
+- Use scoped styles in components: `<style scoped>`
+- Use SCSS variables from Bootstrap and CoreUI when possible
+
+**Routing Conventions**:
+- Use createWebHashHistory for client-side routing (GitHub Pages compatible)
+- Define routes in router/index.js as array of objects
+- Use dynamic imports for lazy loading route components
+- Use exact path matching where needed
+- Public routes (login, register, 404, 500) defined separately
+- Protected routes handled in DefaultLayout
+
+**State Management**:
+- Use Pinia for global state (theme, sidebar visibility)
+- Create stores in stores/ directory
+- Use defineStore() with setup syntax
+- Access stores with const store = useStore()
+- Keep component-level state in ref() or reactive() when state is local
+
+**Naming Conventions**:
+- PascalCase for component files and component names (AppHeader.vue, DefaultLayout.vue)
+- camelCase for variables, functions, and composables (useState, useEffect)
+- UPPER_SNAKE_CASE for constants (API_URL, MAX_ITEMS)
+- kebab-case for CSS classes (following Bootstrap/CoreUI conventions)
+- Descriptive names that indicate purpose (AppHeaderDropdown vs Dropdown)
+
+## Project Structure
+
+```
+coreui-free-vue-admin-template/
+├── public/              # Static assets served directly
+├── src/
+│   ├── assets/         # Images, logos, icons
+│   │   ├── brand/     # Logo components
+│   │   └── images/    # Image files
+│   ├── components/     # Reusable UI components
+│   │   ├── AppHeader.vue
+│   │   ├── AppSidebar.vue
+│   │   ├── AppFooter.vue
+│   │   ├── AppContent.vue
+│   │   ├── AppBreadcrumb.vue
+│   │   └── AppHeaderDropdown.vue
+│   ├── layouts/        # Layout components
+│   │   └── DefaultLayout.vue
+│   ├── views/          # Page components
+│   │   ├── dashboard/ # Dashboard page
+│   │   ├── base/      # Base UI components examples
+│   │   ├── buttons/   # Button examples
+│   │   ├── forms/     # Form examples
+│   │   ├── charts/    # Chart examples
+│   │   ├── icons/     # Icon examples
+│   │   ├── notifications/ # Notification examples
+│   │   ├── widgets/   # Widget examples
+│   │   └── pages/     # Auth & error pages
+│   ├── router/         # Router configuration
+│   │   └── index.js   # Route definitions
+│   ├── stores/         # Pinia stores
+│   ├── scss/           # Stylesheets
+│   │   ├── style.scss # Main stylesheet
+│   │   └── _custom.scss # Custom overrides
+│   ├── App.vue         # Main app component
+│   ├── main.js         # Entry point
+│   └── _nav.js         # Navigation config
+├── index.html          # HTML template
+├── vite.config.mjs     # Vite configuration
+├── eslint.config.mjs   # ESLint configuration
+├── package.json        # Dependencies
+└── README.md           # Documentation
+```
+
+## Development Workflow
+
+**Starting Development**:
+```bash
+npm install          # Install dependencies
+npm run dev          # Start dev server (http://localhost:3000)
+npm run build        # Build for production
+npm run preview      # Preview production build
+npm run lint         # Run ESLint
+```
+
+**Adding a New Page**:
+1. Create component in `src/views/[feature]/ComponentName.vue`
+2. Add route to `src/router/index.js`
+3. Add navigation item to `src/_nav.js` (if needed)
+4. Import and use CoreUI components from '@coreui/vue'
+
+**Creating Components**:
+```vue
+<template>
+  <CCard>
+    <CCardHeader>{{ title }}</CCardHeader>
+    <CCardBody>
+      <slot />
+    </CCardBody>
+  </CCard>
+</template>
+
+<script setup>
+defineProps({
+  title: {
+    type: String,
+    required: true,
+  },
+})
+</script>
+
+<style scoped>
+/* Component-specific styles */
+</style>
+```
+
+**Using Composition API**:
+```vue
+<script setup>
+import { ref, computed, watch, onMounted } from 'vue'
+import { useRouter } from 'vue-router'
+import { useStore } from '@/stores/main'
+
+const data = ref([])
+const store = useStore()
+const router = useRouter()
+
+const filteredData = computed(() => {
+  return data.value.filter(item => item.active)
+})
+
+watch(data, (newValue) => {
+  console.log('Data changed:', newValue)
+})
+
+onMounted(() => {
+  // Fetch data or run initialization
+})
+
+const navigate = () => {
+  router.push('/dashboard')
+}
+</script>
+```
+
+## Code Quality
+
+**Linting**:
+- ESLint configuration in `eslint.config.mjs`
+- Prettier integration for code formatting
+- Vue-specific rules with eslint-plugin-vue
+- Run `npm run lint` before committing
+
+**Best Practices**:
+- Always define props with types and validation
+- Use meaningful component and variable names
+- Keep components small and focused
+- Extract complex logic into composables
+- Use Vue DevTools for debugging
+- Test in both light and dark themes
+- Ensure responsive design works on all screen sizes
+
+**Git Commits**:
+Follow conventional commit format:
+- feat: New feature
+- fix: Bug fix
+- docs: Documentation changes
+- style: Code style changes (formatting)
+- refactor: Code refactoring
+- test: Adding tests
+- chore: Maintenance tasks
+
+## Common Patterns
+
+**Lazy Loading Routes**:
+```javascript
+const Dashboard = () => import('./views/dashboard/Dashboard.vue')
+```
+
+**Composables** (Custom hooks):
+```javascript
+// composables/useFetch.js
+import { ref } from 'vue'
+
+export function useFetch(url) {
+  const data = ref(null)
+  const error = ref(null)
+  const loading = ref(true)
+
+  fetch(url)
+    .then(res => res.json())
+    .then(json => {
+      data.value = json
+    })
+    .catch(err => {
+      error.value = err
+    })
+    .finally(() => {
+      loading.value = false
+    })
+
+  return { data, error, loading }
+}
+```
+
+**Pinia Store**:
+```javascript
+// stores/main.js
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+
+export const useStore = defineStore('main', () => {
+  const sidebarVisible = ref(true)
+  const theme = ref('light')
+
+  function toggleSidebar() {
+    sidebarVisible.value = !sidebarVisible.value
+  }
+
+  function setTheme(newTheme) {
+    theme.value = newTheme
+  }
+
+  return { sidebarVisible, theme, toggleSidebar, setTheme }
+})
+```
+
+**Navigation Configuration** (`_nav.js`):
+```javascript
+export default [
+  {
+    component: 'CNavItem',
+    name: 'Dashboard',
+    to: '/dashboard',
+    icon: 'cil-speedometer',
+  },
+]
+```
+
+## AI Assistant Guidelines
+
+**What AI Should Do**:
+- Generate code using CoreUI Vue components
+- Follow existing code style and conventions
+- Use Composition API with <script setup>
+- Implement responsive designs
+- Define props with proper validation
+- Follow the project's file organization
+- Use existing utility functions and helpers
+- Suggest performance optimizations when appropriate
+
+**What AI Should NOT Do**:
+- Use Options API (use Composition API instead)
+- Import components from libraries other than CoreUI/Vue
+- Suggest Tailwind CSS or other CSS frameworks
+- Ignore ESLint/Prettier rules
+- Create files outside the src/ directory structure
+- Modify build configuration without clear reason
+- Use deprecated Vue patterns
+
+## External Dependencies
+
+**Core Libraries**:
+- @coreui/coreui: ^5.6.1 - CoreUI CSS framework
+- @coreui/vue: ^5.8.0 - CoreUI Vue components
+- @coreui/icons-vue: 2.2.0 - CoreUI icons for Vue
+- vue: ^3.5.31 - Vue framework
+- vue-router: ^5.0.4 - Routing library
+- pinia: ^3.0.4 - State management
+
+**Additional Libraries**:
+- chart.js: ^4.5.1 - Charting library
+- @coreui/vue-chartjs: ^3.0.0 - CoreUI Chart.js wrapper for Vue
+- simplebar-vue: ^2.4.2 - Custom scrollbars
+- @coreui/utils: ^2.0.2 - Utility functions
+
+## Browser Support
+
+Modern browsers with ES6+ support:
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## Resources
+
+- CoreUI Vue Documentation: https://coreui.io/vue/docs/
+- CoreUI Components: https://coreui.io/vue/docs/components/
+- Vue 3 Documentation: https://vuejs.org/
+- Vue Router: https://router.vuejs.org/
+- Pinia: https://pinia.vuejs.org/
+- Vite: https://vitejs.dev/
+
+---
+
+Remember: This is a Vue 3 application using CoreUI Vue components. Always check CoreUI Vue documentation for component APIs and usage examples. Keep the code clean, maintainable, and following Vue 3 best practices with Composition API.

ARCHITECTURE.md

@@ -0,0 +1,716 @@
+# CoreUI Free Vue Admin Template - Architecture
+
+This document provides a comprehensive overview of the CoreUI Free Vue Admin Template architecture, design patterns, and technical implementation details.
+
+## Table of Contents
+
+- [Project Overview](#project-overview)
+- [Technology Stack](#technology-stack)
+- [Architectural Pattern](#architectural-pattern)
+- [Directory Structure](#directory-structure)
+- [Core Components](#core-components)
+- [Routing System](#routing-system)
+- [State Management](#state-management)
+- [Styling Architecture](#styling-architecture)
+- [Build System](#build-system)
+- [Performance Optimizations](#performance-optimizations)
+- [Browser Support](#browser-support)
+
+## Project Overview
+
+The CoreUI Free Vue Admin Template is a professional admin dashboard built on Vue 3, CoreUI Vue components, and Bootstrap 5. It follows modern Vue patterns with Composition API, script setup syntax, and a component-based architecture.
+
+**Key Features**:
+- Single Page Application (SPA) with client-side routing
+- Responsive design with Bootstrap 5 grid system
+- Dark/Light theme support with automatic detection
+- Lazy loading and code splitting for optimal performance
+- Pinia-based state management
+- Modular and extensible component architecture
+
+## Technology Stack
+
+### Frontend Core
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| Vue | 3.5.31 | Progressive framework for building user interfaces |
+| Vue Router | 5.0.4 | Official router for Vue.js |
+| Pinia | 3.0.4 | Official state management library for Vue |
+
+### UI Framework
+
+| Library | Version | Purpose |
+|---------|---------|---------|
+| @coreui/coreui | 5.6.1 | CoreUI CSS framework based on Bootstrap 5 |
+| @coreui/vue | 5.8.0 | CoreUI Vue components |
+| @coreui/icons | 3.0.1 | CoreUI icon set |
+| @coreui/icons-vue | 2.2.0 | CoreUI icons as Vue components |
+| @coreui/utils | 2.0.2 | Utility functions for CoreUI |
+| simplebar-vue | 2.4.2 | Custom scrollbar component |
+
+### Data Visualization
+
+| Library | Version | Purpose |
+|---------|---------|---------|
+| Chart.js | 4.5.1 | HTML5 charting library |
+| @coreui/chartjs | 4.2.0 | CoreUI Chart.js themes and defaults |
+| @coreui/vue-chartjs | 3.0.0 | Vue wrapper for Chart.js with CoreUI styling |
+
+### Build Tools & Development
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| Vite | 8.0.3 | Fast build tool and dev server with HMR |
+| @vitejs/plugin-vue | 6.0.5 | Vite plugin for Vue 3 |
+| Sass | 1.98.0 | CSS preprocessor for styling |
+| PostCSS | 8.5.8 | CSS transformation with autoprefixer |
+| Autoprefixer | 10.4.27 | Automatic vendor prefixing |
+| ESLint | 9.39.4 | JavaScript linting and code quality |
+| eslint-plugin-vue | 10.8.0 | Vue-specific ESLint rules |
+
+### Utilities
+
+| Library | Version | Purpose |
+|---------|---------|---------|
+| @popperjs/core | 2.11.8 | Tooltip and popover positioning |
+
+## Architectural Pattern
+
+### Component-Based Architecture
+
+The application follows a **Composition API architecture** with script setup syntax:
+
+```
+┌──────────────────────────────────────────┐
+│         Application (App.vue)            │
+│  - Router View                           │
+│  - Theme Management                      │
+│  - Route Configuration                   │
+└──────────────────────────────────────────┘
+                    ↓
+    ┌───────────────┴────────────────┐
+    │                                │
+┌───▼────┐                  ┌────────▼───────┐
+│ Public │                  │   Protected    │
+│ Routes │                  │     Routes     │
+│        │                  │(DefaultLayout) │
+│ Login  │                  └───────┬────────┘
+│Register│                          │
+│ 404    │              ┌───────────┼────────────┐
+│ 500    │              │           │            │
+└────────┘         ┌────▼────┐ ┌────▼─────┐ ┌────▼─────┐
+                   │AppHeader│ │AppSidebar│ │AppContent│
+                   └─────────┘ └──────────┘ └────┬─────┘
+                                                 │
+                                         ┌───────▼─────────┐
+                                         │ View Components │
+                                         │ (Dashboard,     │
+                                         │  Forms, etc.)   │
+                                         └─────────────────┘
+```
+
+### Single Page Application (SPA) Pattern
+
+The template uses client-side routing with createWebHashHistory:
+1. **Initial Load**: HTML shell loads, Vue initializes
+2. **Route Matching**: Vue Router matches URL to component
+3. **Lazy Loading**: Component bundles load on-demand
+4. **Rendering**: Component renders with layout wrapper
+5. **Navigation**: Client-side transitions without page reload
+
+### State Management Pattern
+
+Pinia manages global application state:
+
+```javascript
+Store (stores/)
+  ├── sidebarVisible (boolean)
+  ├── sidebarUnfoldable (boolean)
+  └── theme (string: light/dark/auto)
+```
+
+Component-level state uses Vue's Composition API (ref, reactive).
+
+## Directory Structure
+
+```
+coreui-free-vue-admin-template/
+│
+├── public/                      # Static assets (served as-is)
+│   ├── favicon.ico
+│   └── robots.txt
+│
+├── src/                         # Source code
+│   │
+│   ├── assets/                  # Application assets
+│   │   ├── brand/              # Logo components (logo.js, sygnet.js)
+│   │   └── images/             # Image files (avatars, etc.)
+│   │
+│   ├── components/              # Reusable UI components
+│   │   ├── AppBreadcrumb.vue   # Breadcrumb navigation
+│   │   ├── AppContent.vue      # Main content area wrapper
+│   │   ├── AppFooter.vue       # Footer component
+│   │   ├── AppHeader.vue       # Header component
+│   │   ├── AppHeaderDropdown.vue # User dropdown menu
+│   │   ├── AppSidebar.vue      # Sidebar navigation
+│   │   ├── DocsComponents.vue  # Documentation component showcase
+│   │   └── DocsExample.vue     # Code example wrapper
+│   │
+│   ├── layouts/                 # Layout wrapper components
+│   │   └── DefaultLayout.vue   # Main application layout
+│   │
+│   ├── views/                   # Page/view components
+│   │   ├── dashboard/          # Dashboard page
+│   │   │   ├── Dashboard.vue
+│   │   │   └── MainChart.vue
+│   │   ├── base/               # Base UI component examples
+│   │   │   ├── Accordion.vue
+│   │   │   ├── Breadcrumbs.vue
+│   │   │   ├── Cards.vue
+│   │   │   ├── Carousels.vue
+│   │   │   ├── Chips.vue
+│   │   │   ├── Collapses.vue
+│   │   │   ├── ListGroups.vue
+│   │   │   ├── Navs.vue
+│   │   │   ├── Paginations.vue
+│   │   │   ├── Placeholders.vue
+│   │   │   ├── Popovers.vue
+│   │   │   ├── Progress.vue
+│   │   │   ├── Spinners.vue
+│   │   │   ├── Tables.vue
+│   │   │   ├── Tabs.vue
+│   │   │   └── Tooltips.vue
+│   │   ├── buttons/            # Button examples
+│   │   ├── charts/             # Chart examples
+│   │   ├── forms/              # Form examples
+│   │   │   └── ChipInput.vue
+│   │   ├── icons/              # Icon examples
+│   │   ├── notifications/      # Notification examples
+│   │   ├── widgets/            # Widget examples
+│   │   ├── theme/              # Theme examples
+│   │   └── pages/              # Special pages
+│   │       ├── Login.vue       # Login page
+│   │       ├── Register.vue    # Registration page
+│   │       ├── Page404.vue     # 404 error page
+│   │       └── Page500.vue     # 500 error page
+│   │
+│   ├── router/                  # Router configuration
+│   │   └── index.js            # Route definitions
+│   │
+│   ├── stores/                  # Pinia stores (if created)
+│   │
+│   ├── scss/                    # Global stylesheets
+│   │   ├── style.scss          # Main stylesheet (imports CoreUI)
+│   │   └── _custom.scss        # Custom style overrides
+│   │
+│   ├── App.vue                  # Root application component
+│   ├── main.js                  # Application entry point
+│   └── _nav.js                  # Sidebar navigation configuration
+│
+├── node_modules/                # Dependencies
+├── index.html                   # HTML entry point
+├── vite.config.mjs              # Vite build configuration
+├── eslint.config.mjs            # ESLint configuration
+├── package.json                 # Project metadata and dependencies
+├── .browserslistrc              # Browser compatibility targets
+├── .editorconfig                # Editor configuration
+└── README.md                    # Project documentation
+```
+
+## Core Components
+
+### Application Component (App.vue)
+
+The root component that:
+- Sets up router-view for component rendering
+- Manages theme initialization
+- Provides the application shell
+
+**Key Features**:
+- Theme detection and persistence
+- Suspense boundaries for lazy-loaded routes
+- Global error handling boundaries
+
+### Layout System
+
+#### DefaultLayout (layouts/DefaultLayout.vue)
+
+The main application layout wrapper that composes:
+- **AppSidebar**: Collapsible navigation sidebar
+- **AppHeader**: Top navigation bar with breadcrumbs and user menu
+- **AppContent**: Main content area with routing
+- **AppFooter**: Footer with version and links
+
+**Responsibility**: Provides consistent layout structure for authenticated views.
+
+#### Navigation Components
+
+**AppSidebar** (`components/AppSidebar.vue`):
+- Renders collapsible sidebar
+- Uses Pinia for show/hide state
+- Integrates with _nav.js for menu structure
+- Includes branding section
+
+**AppHeader** (`components/AppHeader.vue`):
+- Fixed top navigation bar
+- Sidebar toggle button
+- Breadcrumb navigation
+- User dropdown menu
+- Theme switcher
+
+### View Components
+
+View components are page-level components that:
+- Render specific application features (Dashboard, Forms, Charts)
+- Use CoreUI Vue components for UI
+- Connect to Pinia when needed for global state
+- Implement business logic and data fetching
+
+**Example Structure**:
+```vue
+<template>
+  <CCard>
+    <CCardBody>
+      {{ data }}
+    </CCardBody>
+  </CCard>
+</template>
+
+<script setup>
+import { ref, onMounted } from 'vue'
+
+const data = ref([])
+
+onMounted(() => {
+  // Fetch dashboard data
+})
+</script>
+```
+
+## Routing System
+
+### Vue Router v5
+
+The application uses Vue Router for declarative routing:
+
+**Configuration** (`router/index.js`):
+```javascript
+import { createRouter, createWebHashHistory } from 'vue-router'
+
+const routes = [
+  {
+    path: '/',
+    name: 'Home',
+    component: DefaultLayout,
+    redirect: '/dashboard',
+    children: [
+      {
+        path: '/dashboard',
+        name: 'Dashboard',
+        component: () => import('@/views/dashboard/Dashboard.vue'),
+      },
+    ],
+  },
+  {
+    path: '/pages',
+    redirect: '/pages/404',
+    name: 'Pages',
+    component: {
+      render() {
+        return h(resolveComponent('router-view'))
+      },
+    },
+    children: [
+      {
+        path: '404',
+        name: 'Page404',
+        component: () => import('@/views/pages/Page404'),
+      },
+    ],
+  },
+]
+
+const router = createRouter({
+  history: createWebHashHistory(import.meta.env.BASE_URL),
+  routes,
+  scrollBehavior() {
+    return { top: 0 }
+  },
+})
+
+export default router
+```
+
+### Lazy Loading & Code Splitting
+
+All routes use dynamic imports for lazy loading:
+
+```javascript
+component: () => import('./views/dashboard/Dashboard.vue')
+```
+
+**Benefits**:
+- Smaller initial bundle size
+- Faster first page load
+- Components load only when navigated to
+- Automatic code splitting by Vite
+
+### Navigation Configuration
+
+Navigation structure defined in `_nav.js`:
+
+```javascript
+export default [
+  {
+    component: 'CNavItem',
+    name: 'Dashboard',
+    to: '/dashboard',
+    icon: 'cil-speedometer',
+    badge: {
+      color: 'info',
+      text: 'NEW',
+    },
+  },
+  {
+    component: 'CNavGroup',
+    name: 'Base',
+    icon: 'cil-puzzle',
+    items: [
+      {
+        component: 'CNavItem',
+        name: 'Accordion',
+        to: '/base/accordion',
+      },
+    ],
+  },
+]
+```
+
+## State Management
+
+### Pinia Store Architecture
+
+Pinia uses the Composition API pattern:
+
+**Store Example** (`stores/main.js`):
+
+```javascript
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+
+export const useStore = defineStore('main', () => {
+  const sidebarVisible = ref(true)
+  const sidebarUnfoldable = ref(false)
+  const theme = ref('light')
+
+  function toggleSidebar() {
+    sidebarVisible.value = !sidebarVisible.value
+  }
+
+  function setSidebarUnfoldable(value) {
+    sidebarUnfoldable.value = value
+  }
+
+  function setTheme(value) {
+    theme.value = value
+  }
+
+  return {
+    sidebarVisible,
+    sidebarUnfoldable,
+    theme,
+    toggleSidebar,
+    setSidebarUnfoldable,
+    setTheme,
+  }
+})
+```
+
+### State Usage in Components
+
+**Reading State**:
+```vue
+<script setup>
+import { useStore } from '@/stores/main'
+
+const store = useStore()
+// Access: store.sidebarVisible
+</script>
+```
+
+**Updating State**:
+```vue
+<script setup>
+import { useStore } from '@/stores/main'
+
+const store = useStore()
+
+const toggleSidebar = () => {
+  store.toggleSidebar()
+}
+</script>
+```
+
+## Styling Architecture
+
+### Sass/SCSS Structure
+
+**Main Stylesheet** (`src/scss/style.scss`):
+```scss
+@use "@coreui/coreui/scss/coreui" as * with (
+  $enable-deprecation-messages: false
+);
+
+// Custom variables and overrides
+@import 'custom';
+```
+
+**Custom Overrides** (`src/scss/_custom.scss`):
+```scss
+// Override CoreUI/Bootstrap variables
+$primary: #321fdb;
+$secondary: #ced2d8;
+
+// Custom styles
+.my-custom-class {
+  // styles
+}
+```
+
+### CSS Custom Properties (CSS Variables)
+
+CoreUI uses CSS custom properties for theming:
+
+```css
+:root {
+  --cui-primary: #321fdb;
+  --cui-secondary: #ced2d8;
+  --cui-body-bg: #ebedef;
+  --cui-body-color: #4f5d73;
+}
+
+[data-coreui-theme="dark"] {
+  --cui-body-bg: #2b3035;
+  --cui-body-color: #b4bac0;
+}
+```
+
+**Usage in Components**:
+```vue
+<template>
+  <div :style="{ backgroundColor: 'var(--cui-primary)' }">Content</div>
+</template>
+```
+
+### Component Styling
+
+**Scoped Styles**:
+```vue
+<style scoped>
+.my-component {
+  padding: 1rem;
+  background-color: var(--cui-light);
+}
+</style>
+```
+
+**Class Bindings**:
+```vue
+<template>
+  <button :class="['btn', { 'btn-primary': isPrimary, 'active': isActive }]">
+    Click
+  </button>
+</template>
+```
+
+**Bootstrap Utilities**:
+```vue
+<template>
+  <CCard class="mb-4 shadow-sm">
+    <CCardBody class="p-4 d-flex justify-content-between">
+    </CCardBody>
+  </CCard>
+</template>
+```
+
+## Build System
+
+### Vite Configuration
+
+**File**: `vite.config.mjs`
+
+```javascript
+import { fileURLToPath, URL } from 'node:url'
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import autoprefixer from 'autoprefixer'
+
+export default defineConfig({
+  plugins: [vue()],
+  resolve: {
+    alias: {
+      '@': fileURLToPath(new URL('./src', import.meta.url)),
+    },
+    extensions: ['.js', '.json', '.jsx', '.mjs', '.ts', '.tsx', '.vue'],
+  },
+  server: {
+    port: 3000,
+  },
+  css: {
+    postcss: {
+      plugins: [autoprefixer()],
+    },
+  },
+})
+```
+
+### Build Process
+
+**Development Build**:
+1. Vite starts dev server on port 3000
+2. esbuild compiles Vue SFC components
+3. PostCSS processes Sass/SCSS with autoprefixer
+4. Hot Module Replacement (HMR) for instant updates
+
+**Production Build**:
+1. `vite build` command
+2. Code minification and tree-shaking
+3. Asset optimization (images, fonts)
+4. CSS extraction and minification
+5. Source maps generation
+6. Output to `dist/` directory
+
+**Build Output**:
+```
+dist/
+├── assets/
+│   ├── index-[hash].js      # Main bundle
+│   ├── [component]-[hash].js # Lazy-loaded chunks
+│   └── index-[hash].css     # Extracted CSS
+├── index.html               # HTML entry
+└── favicon.ico              # Static assets
+```
+
+### Code Splitting Strategy
+
+**Automatic Splitting**:
+- Each lazy-loaded route becomes a separate chunk
+- Vendor libraries (Vue, CoreUI) in separate vendor chunk
+- Dynamic imports create split points
+
+**Manual Splitting** (if needed):
+```javascript
+const HeavyComponent = () => import(/* webpackChunkName: "heavy" */ './HeavyComponent.vue')
+```
+
+## Performance Optimizations
+
+### Implemented Optimizations
+
+1. **Lazy Loading**: All routes lazy-loaded with dynamic imports
+2. **Code Splitting**: Separate bundles per route
+3. **Tree Shaking**: Unused code eliminated by Vite
+4. **Asset Optimization**: Images and fonts optimized
+5. **CSS Extraction**: Separate CSS bundle for caching
+6. **Hash-based Caching**: File names include content hash
+
+### Component Optimization
+
+**v-memo** for expensive renders:
+```vue
+<template>
+  <div v-memo="[valueA, valueB]">
+    <!-- Heavy rendering -->
+  </div>
+</template>
+```
+
+**computed** for derived values:
+```vue
+<script setup>
+import { computed } from 'vue'
+
+const sortedData = computed(() => {
+  return data.value.sort((a, b) => a.value - b.value)
+})
+</script>
+```
+
+### Bundle Size Management
+
+**Strategies**:
+- Use named imports: `import { CButton } from '@coreui/vue'`
+- Avoid importing entire libraries
+- Check bundle size with `npm run build`
+- Use Vite's rollup visualizer for analysis
+
+## Browser Support
+
+### Target Browsers
+
+Defined in `.browserslistrc`:
+```
+> 0.5%
+last 2 versions
+Firefox ESR
+not dead
+not IE 11
+```
+
+### Polyfills
+
+Modern browsers support Vue 3 natively. No additional polyfills needed for ES6+ features.
+
+### Progressive Enhancement
+
+- Modern features with fallbacks
+- CSS Grid with flexbox fallback
+- Modern color modes with theme classes
+
+## Security Considerations
+
+### Best Practices
+
+1. **Content Security Policy**: Configure CSP headers
+2. **XSS Prevention**: Vue escapes content by default
+3. **Dependency Auditing**: Run `npm audit` regularly
+4. **Environment Variables**: Use `.env` files (not committed)
+5. **HTTPS**: Serve over HTTPS in production
+
+### Vue Security
+
+- Avoid `v-html` unless necessary and sanitize content
+- Validate user input before rendering
+- Use prop validation for type safety
+- Keep dependencies updated
+
+## Deployment
+
+### Static Hosting
+
+The application builds to static files suitable for:
+- Netlify
+- Vercel
+- GitHub Pages
+- AWS S3 + CloudFront
+- Any static file server
+
+### Build for Production
+
+```bash
+npm run build
+```
+
+Output in `dist/` directory ready for deployment.
+
+### HashRouter for Static Hosts
+
+Uses createWebHashHistory for GitHub Pages compatibility:
+- URLs: `https://example.com/#/dashboard`
+- No server-side routing configuration needed
+- Works with any static host
+
+---
+
+This architecture provides a solid foundation for building modern, performant admin dashboards with Vue 3 and CoreUI. The modular structure allows for easy extension and customization while maintaining code quality and best practices.

README.md

@@ -1,4 +1,4 @@
-# CoreUI Free Vue Admin Template [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social&logo=twitter)](https://twitter.com/intent/tweet?text=CoreUI%20-%20Free%Vue%204%20Admin%20Template%20&url=https://coreui.io&hashtags=bootstrap,admin,template,dashboard,panel,free,angular,react,vue)
+# CoreUI Free Vue Admin Template - Built for AI-Assisted Development [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social&logo=twitter)](https://twitter.com/intent/tweet?text=CoreUI%20-%20Free%Vue%204%20Admin%20Template%20&url=https://coreui.io&hashtags=bootstrap,admin,template,dashboard,panel,free,angular,react,vue)
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 [![@coreui coreui](https://img.shields.io/badge/@coreui%20-coreui-lightgrey.svg?style=flat-square)](https://github.com/coreui/coreui)
@@ -29,6 +29,7 @@ CoreUI is meant to be the UX game changer. Pure & transparent code is devoid of
 * [Installation](#installation)
 * [Basic usage](#basic-usage)
 * [What's included](#whats-included)
+* [AI-Friendly Development](#ai-friendly-development)
 * [Documentation](#documentation)
 * [Components](#components)
 * [Versioning](#versioning)
@@ -135,6 +136,43 @@ coreui-free-vue-admin-template
 └── vite.config.mjs
 ```
 
+## AI-Friendly Development
+
+This template is designed to work seamlessly with AI coding assistants like Cursor, GitHub Copilot, and Claude Code. We've included comprehensive documentation and configuration files to help AI understand the project structure and conventions.
+
+### Features for AI Development
+
+- **`.cursorrules`**: Complete AI assistant configuration with project conventions, technology stack, and coding patterns
+- **`ARCHITECTURE.md`**: Detailed technical architecture documentation covering components, routing, state management, and build system
+- **`DEVELOPMENT.md`**: Comprehensive development guide with setup instructions, workflows, and best practices
+- **JSDoc Comments**: Main Vue components include documentation for better AI understanding
+
+### Getting Started with AI Assistants
+
+1. **Open the project** in your AI-powered IDE (VS Code with Cursor, GitHub Copilot, or Claude Code)
+2. **Review `.cursorrules`** to understand the project conventions
+3. **Ask your AI assistant** to help you build features - it will automatically follow the project patterns
+4. **Use natural language** to describe components, pages, or features you want to add
+
+### What AI Assistants Know About This Project
+
+Your AI assistant understands:
+- **Component Library**: Always use CoreUI Vue components (never Tailwind, Vuetify, or other libraries)
+- **Code Style**: Vue 3 Composition API with `<script setup>` syntax, Prettier formatting, ESLint rules
+- **Architecture**: Single Page Application with Vue Router, Pinia for state management, Vite for building
+- **File Organization**: Where to create components, views, routes, and styles
+- **Common Patterns**: Lazy loading, composables, navigation configuration, theming
+
+### Example AI Prompts
+
+Try asking your AI assistant:
+- "Create a new products page with a table showing product name, price, and status"
+- "Add a user profile form with validation"
+- "Create a chart showing monthly sales data"
+- "Add a new navigation item for the settings page"
+
+For more information, see the [DEVELOPMENT.md](DEVELOPMENT.md) guide.
+
 ## Documentation
 
 The documentation for the CoreUI Admin Template is hosted at our website [CoreUI for Vue](https://coreui.io/vue/docs/templates/installation.html)

src/App.vue

@@ -1,9 +1,23 @@
 <script setup>
+/**
+ * App.vue - Main Application Component
+ *
+ * This is the root component of the CoreUI Free Vue Admin Template.
+ * It handles theme initialization and provides the router-view for all routes.
+ *
+ * Key responsibilities:
+ * - Theme detection from URL parameters
+ * - Theme persistence with localStorage
+ * - Router view rendering for SPA navigation
+ *
+ * @component
+ */
 import { onBeforeMount } from 'vue'
 import { useColorModes } from '@coreui/vue'
 
 import { useThemeStore } from '@/stores/theme.js'
 
+// Initialize CoreUI color modes with local storage key
 const { isColorModeSet, setColorMode } = useColorModes(
   'coreui-free-vue-admin-template-theme',
 )

src/_nav.js

@@ -1,3 +1,26 @@
+/**
+ * _nav.js - Sidebar Navigation Configuration
+ *
+ * This file defines the structure and content of the sidebar navigation menu.
+ * The navigation is rendered by AppSidebar component using CoreUI nav components.
+ *
+ * Navigation item types:
+ * - CNavItem: Single navigation link
+ * - CNavGroup: Expandable group of navigation items
+ * - CNavTitle: Section title/divider
+ *
+ * Each item can have:
+ * - component: CoreUI component type ('CNavItem', 'CNavGroup', 'CNavTitle')
+ * - name: Display text
+ * - to: Vue Router path (for CNavItem)
+ * - icon: CoreUI icon name (from @coreui/icons)
+ * - badge: Optional badge with color and text
+ * - items: Array of child items (for CNavGroup)
+ * - href: External link URL
+ * - external: Boolean for external links
+ *
+ * @type {Array<Object>}
+ */
 export default [
   {
     component: 'CNavItem',

src/main.js

@@ -1,24 +1,52 @@
+/**
+ * main.js - Application Entry Point
+ *
+ * This file initializes the Vue 3 application and configures:
+ * - Pinia for state management
+ * - Vue Router for client-side routing
+ * - CoreUI Vue component library
+ * - Global icon system
+ * - Documentation helper components
+ *
+ * The application uses:
+ * - Vue 3 Composition API
+ * - Vite for building and development
+ * - CoreUI Vue components
+ * - Hash-based routing for static hosting compatibility
+ */
+
 import { createApp } from 'vue'
 import { createPinia } from 'pinia'
 
 import App from './App.vue'
 import router from './router'
 
+// CoreUI Vue components and icons
 import CoreuiVue from '@coreui/vue'
 import CIcon from '@coreui/icons-vue'
 import { iconsSet as icons } from '@/assets/icons'
+
+// Documentation components (remove in production if not needed)
 import DocsComponents from '@/components/DocsComponents'
 import DocsExample from '@/components/DocsExample'
 import DocsIcons from '@/components/DocsIcons'
 
+// Create Vue application instance
 const app = createApp(App)
-app.use(createPinia())
+
-app.use(router)
+// Install plugins
-app.use(CoreuiVue)
+app.use(createPinia()) // State management
+app.use(router) // Router for SPA navigation
+app.use(CoreuiVue) // CoreUI component library
+
+// Provide icons globally
 app.provide('icons', icons)
+
+// Register global components
 app.component('CIcon', CIcon)
 app.component('DocsComponents', DocsComponents)
 app.component('DocsExample', DocsExample)
 app.component('DocsIcons', DocsIcons)
 
+// Mount application to DOM
 app.mount('#app')

src/router/index.js

@@ -1,8 +1,36 @@
+/**
+ * router/index.js - Vue Router Configuration
+ *
+ * This file configures the application routing using Vue Router 5.
+ * It defines all routes and navigation structure for the SPA.
+ *
+ * Routing Features:
+ * - Hash-based routing (createWebHashHistory) for static hosting compatibility
+ * - Lazy loading for all route components (code splitting)
+ * - Nested routes for layout-based navigation
+ * - Automatic scroll to top on navigation
+ *
+ * Route Structure:
+ * - Protected routes: Wrapped in DefaultLayout with sidebar and header
+ * - Public routes: Login, Register, 404, 500 pages without layout
+ *
+ * Adding New Routes:
+ * 1. Import component (use dynamic import for code splitting)
+ * 2. Add route object to appropriate section
+ * 3. Update _nav.js for sidebar navigation (if needed)
+ *
+ * @see https://router.vuejs.org/
+ */
+
 import { h, resolveComponent } from 'vue'
 import { createRouter, createWebHashHistory } from 'vue-router'
 
 import DefaultLayout from '@/layouts/DefaultLayout'
 
+/**
+ * Application routes configuration
+ * @type {Array<Object>}
+ */
 const routes = [
   {
     path: '/',