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.

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)
-app.use(CoreuiVue)
+
+// Install plugins
+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: '/',