{"owner":"coreui","repo":"coreui-free-bootstrap-admin-template","hasSkills":true,"totalSkillsCount":2,"totalTokensCount":6061,"categories":["project-spec","cursor-rule"],"hasMcp":false,"mcpConfig":null,"found":["ARCHITECTURE.md",".cursorrules"],"skills":{"ARCHITECTURE.md":"# Architecture Documentation\n\n## Project Purpose\n\nCoreUI Free Bootstrap Admin Template is a professional admin dashboard template built on Bootstrap 5 and CoreUI components. It provides a ready-to-use foundation for building admin panels, dashboards, and web applications with a clean, modern interface.\n\n**Key Characteristics:**\n- Server-side templating approach (Pug → HTML)\n- Bootstrap 5 + CoreUI component library\n- Vanilla JavaScript (no framework dependencies)\n- Multi-page application (MPA) architecture\n- Static file generation with build-time compilation\n\n## High-Level Architecture\n\n```\n┌─────────────────────────────────────────────────────┐\n│                   Source Files                      │\n│  ┌──────────┐  ┌──────────┐  ┌──────────┐           │\n│  │   Pug    │  │   Sass   │  │    JS    │           │\n│  │Templates │  │  Styles  │  │ Modules  │           │\n│  └────┬─────┘  └────┬─────┘  └────┬─────┘           │\n│       │             │             │                 │\n└───────┼─────────────┼─────────────┼─────────────────┘\n        │             │             │\n        ▼             ▼             ▼\n┌─────────────────────────────────────────────────────┐\n│                  Build Pipeline                     │\n│  ┌──────────┐  ┌──────────┐  ┌──────────┐           │\n│  │   Pug    │  │PostCSS + │  │ syncdir  │           │\n│  │Compiler  │  │  Sass    │  │(copy JS) │           │\n│  └────┬─────┘  └────┬─────┘  └────┬─────┘           │\n│       │             │             │                 │\n└───────┼─────────────┼─────────────┼─────────────────┘\n        │             │             │\n        ▼             ▼             ▼\n┌─────────────────────────────────────────────────────┐\n│                 Distribution Files                  │\n│  ┌──────────┐  ┌──────────┐  ┌──────────┐           │\n│  │   HTML   │  │   CSS    │  │    JS    │           │\n│  │  Files   │  │ (minified)│  │(bundled) │          │\n│  └──────────┘  └──────────┘  └──────────┘           │\n│         (served via browser-sync or web server)     │\n└─────────────────────────────────────────────────────┘\n```\n\n## Technology Stack\n\n### Frontend\n- **HTML Generation**: Pug 3.0.3 (template engine)\n- **CSS Framework**: Bootstrap 5.3.x\n- **Component Library**: CoreUI 5.x (@coreui/coreui)\n- **Icons**: CoreUI Icons (@coreui/icons)\n- **JavaScript**: Vanilla ES6+ (no framework)\n- **Charts**: Chart.js 4.x\n- **Scrollbars**: SimpleBar 6.x\n\n### Build Tools\n- **Package Manager**: npm\n- **CSS Processing**: Sass 1.102.x → PostCSS → Autoprefixer\n- **JS**: plain ES2015+, copied as-is via `sync-directory` (no transpilation - the declared browser targets already support the syntax used, see [Browser Support](#browser-support))\n- **Task Runner**: npm scripts with npm-run-all\n- **File Watching**: Nodemon\n- **Live Server**: Browser-sync 3.0.4\n\n### Code Quality\n- **Linting**: ESLint 9.x (flat config) with XO + Unicorn\n- **Style Linting**: Stylelint 16.x with Bootstrap config\n- **Formatting**: Prettier 3.9.x\n- **Editor Config**: .editorconfig for consistency\n\n## Directory Structure\n\n```\ncoreui-free-bootstrap-admin-template/\n│\n├── src/                          # Source files (edit these)\n│   ├── pug/                      # Pug templates (HTML source)\n│   │   ├── _layout/              # Base layout templates\n│   │   │   ├── default.pug       # Main layout with sidebar/header\n│   │   │   └── pages.pug         # Standalone pages layout (auth, errors)\n│   │   ├── _partials/            # Reusable components\n│   │   │   ├── banner.pug        # Top announcement banner\n│   │   │   ├── head.pug          # HTML <head> section\n│   │   │   ├── header.pug        # Top navigation bar\n│   │   │   ├── sidebar.pug       # Left sidebar wrapper\n│   │   │   ├── sidebar-nav.pug   # Sidebar navigation items (data-driven)\n│   │   │   ├── footer.pug        # Page footer\n│   │   │   ├── scripts.pug       # Common script includes\n│   │   │   └── docs-icons.pug    # Icon documentation helpers\n│   │   ├── _mixins/              # Pug helper mixins\n│   │   │   ├── breadcrumb.pug    # Breadcrumb generator\n│   │   │   ├── callout.pug       # Alert/callout boxes\n│   │   │   ├── callout-custom.pug # Custom callout variant\n│   │   │   ├── docs-components.pug # Docs component helpers\n│   │   │   ├── example.pug       # Code example displays\n│   │   │   └── inline-svg.pug    # Inline SVG helper\n│   │   └── views/                # Page templates\n│   │       ├── index.pug         # Main dashboard page\n│   │       ├── blank.pug         # Blank page template\n│   │       ├── charts.pug        # Charts page\n│   │       ├── widgets.pug       # Widgets page\n│   │       ├── authentication/   # Auth pages (login, register, etc.)\n│   │       ├── components/       # UI components (buttons, modals, etc.)\n│   │       ├── error-pages/      # Error pages (404, 500)\n│   │       ├── forms/            # Form components\n│   │       └── icons/            # Icon libraries\n│   │\n│   ├── scss/                     # Sass stylesheets\n│   │   ├── style.scss            # Main stylesheet entry\n│   │   ├── style-rtl.scss        # RTL (right-to-left) styles\n│   │   └── examples.scss         # Demo/example page styles\n│   │\n│   ├── js/                       # JavaScript modules\n│   │   ├── main.js               # Main entry point\n│   │   ├── charts.js             # Chart.js configurations\n│   │   ├── color-modes.js        # Dark/light theme switcher\n│   │   ├── config.js             # App configuration / shared settings\n│   │   ├── tooltips.js           # Tooltip initialization\n│   │   ├── popovers.js           # Popover initialization\n│   │   ├── toasts.js             # Toast notification initialization\n│   │   └── widgets.js            # Widgets page charts\n│   │\n│   ├── assets/                   # Static assets\n│   │   ├── brand/                # Logo files\n│   │   ├── favicon/              # Favicon files\n│   │   └── img/                  # Images\n│   │\n│   └── views/                    # Compiled HTML (auto-generated)\n│       └── *.html                # Do NOT edit these manually\n│\n├── dist/                         # Production build output\n│   ├── css/                      # Minified CSS\n│   ├── js/                       # Synced JS (copied as-is, no transform)\n│   ├── assets/                   # Copied assets\n│   ├── vendors/                  # Third-party libraries\n│   └── *.html                    # Production HTML files\n│\n├── build/                        # Build scripts\n│   ├── pug.mjs                   # Pug compilation script\n│   ├── postcss.config.mjs        # PostCSS configuration\n│   ├── vendors.mjs               # Vendor file bundling\n│   └── format-html.mjs           # HTML formatting/prettifying\n│\n├── node_modules/                 # npm dependencies (ignored)\n│\n└── Configuration files\n    ├── package.json              # Dependencies and scripts\n    ├── .editorconfig             # Editor settings\n    ├── eslint.config.mjs         # ESLint flat config\n    ├── .prettierrc.json          # Prettier formatting\n    ├── .stylelintrc              # Stylelint rules\n    ├── .browserslistrc           # Target browsers\n    └── .cursorrules              # AI context (Cursor IDE)\n```\n\n## Build Pipeline Details\n\n### Development Mode (`npm start`)\n\n1. **Clean**: Remove old compiled files\n2. **Compile Pug**: `src/pug/**/*.pug` → `src/views/*.html`\n3. **Compile Sass**: `src/scss/*.scss` → `dist/css/*.css` (expanded, autoprefixed)\n4. **Sync JS**: `src/js/*.js` → `dist/js/*.js` (copied as-is via `sync-directory`, no transform)\n5. **Copy Assets**: `src/assets/**/*` → `dist/assets/`\n6. **Build Vendors**: Bundle third-party libraries\n7. **Watch Files**: Monitor changes and recompile\n8. **Browser-sync**: Live reload server on http://localhost:3000\n\n### Production Build (`npm run build`)\n\n1. **All development steps**\n2. **Minify CSS**: Compress stylesheets with clean-css-cli\n3. **JS**: No separate minify step - shipped as synced source\n4. **Optimize Assets**: Copy optimized files\n5. **Generate zip**: Create distribution package\n\n### File Watching\n\n```\nnpm run watch          # Watch all file types\nnpm run watch-pug      # Watch Pug templates only\nnpm run watch-css      # Watch Sass files only\nnpm run watch-js       # Watch JavaScript files only\n```\n\nEach watch task uses **nodemon** to monitor file changes and trigger appropriate compilation.\n\n## Data Flow\n\n### Page Rendering Flow\n\n```\n1. Browser Request\n   └─> /index.html\n\n2. Server Response\n   └─> Serve dist/index.html (static file)\n\n3. HTML Loads Resources\n   ├─> dist/css/style.css (Bootstrap + CoreUI + custom styles)\n   ├─> dist/js/main.js (app initialization)\n   └─> dist/vendors/*.js (Chart.js, SimpleBar, etc.)\n\n4. JavaScript Execution\n   ├─> Initialize CoreUI components\n   ├─> Set up event listeners\n   ├─> Configure charts (if on dashboard)\n   └─> Enable tooltips/popovers\n\n5. User Interaction\n   └─> JavaScript handles UI updates (no page reload)\n```\n\n### Theme Switching Flow\n\n```\n1. User clicks theme toggle button\n   └─> color-modes.js listens for click\n\n2. ColorModeStorageManager updates preference\n   ├─> Save to localStorage\n   └─> Update [data-coreui-theme] attribute\n\n3. CSS custom properties respond\n   └─> Variables change (--cui-primary-bg, --cui-text-color, etc.)\n\n4. ColorSchemeChange event fires\n   └─> Charts re-render with new theme colors\n```\n\n### Chart Rendering Flow\n\n```\n1. charts.js module loads\n   └─> import Chart from 'chart.js/auto'\n\n2. DOM ready\n   └─> Find chart canvas elements\n\n3. Fetch data (or use inline data)\n   └─> Random data generator for demo\n\n4. Create Chart.js instance\n   ├─> Configure chart type (line, bar, pie, etc.)\n   ├─> Apply theme colors from CSS variables\n   └─> Set responsive options\n\n5. Theme changes\n   └─> Re-initialize charts with new colors\n```\n\n## Component Organization\n\n### Pug Template Hierarchy\n\n```\ndefault.pug (main layout — dashboard/component pages)\n├─> sidebar.pug (side navigation)\n│   └─> sidebar-nav.pug (data-driven nav items)\n├─> header.pug (top navigation bar)\n│   └─> block breadcrumb\n├─> block canonical / block styles\n├─> block view\n│   └─> index.pug / components/*.pug / etc. (page content)\n└─> footer.pug (page footer)\n    └─> scripts.pug (common script includes)\n        └─> block scripts / block js\n\npages.pug (standalone layout — auth & error pages)\n├─> block styles\n└─> block view\n    └─> authentication/*.pug / error-pages/*.pug\n```\n\n**Block System:**\n- `block view`: Main page content area (both layouts)\n- `block canonical`: `<link rel=\"canonical\">` override (`default.pug` only)\n- `block breadcrumb`: Breadcrumb trail, declared inside `header.pug` (`default.pug` only)\n- `block scripts` / `block js`: Page-specific script includes, declared inside `scripts.pug`\n- Each view extends a layout and overrides only the blocks it needs\n\n### CSS Architecture\n\n```\nstyle.scss\n├─> Import Bootstrap 5\n├─> Import CoreUI components\n├─> Import custom variables\n└─> Import custom component styles\n\nTheme System:\n[data-coreui-theme=\"light\"]  # Light mode (default)\n[data-coreui-theme=\"dark\"]   # Dark mode\n[data-coreui-theme=\"auto\"]   # System preference\n```\n\n**CSS Custom Properties:**\n- `--cui-primary`, `--cui-secondary`, etc. (colors)\n- `--cui-bg`, `--cui-text-color` (backgrounds/text)\n- `--cui-border-color`, `--cui-shadow` (UI elements)\n\n### JavaScript Module Pattern\n\nEach JS file in `src/js/` is an ES6 module:\n\n```javascript\n// Import dependencies\nimport { Something } from '@coreui/coreui'\n\n// Define functionality\nconst doSomething = () => { /* ... */ }\n\n// Initialize on DOM ready\ndocument.addEventListener('DOMContentLoaded', () => {\n  doSomething()\n})\n\n// Export if needed (most files use side effects only)\n```\n\n## Key Dependencies\n\n### Runtime Dependencies\n\n| Package | Purpose | Used In |\n|---------|---------|---------|\n| `@coreui/coreui` | UI component library | All pages |\n| `@coreui/icons` | Icon library | Icon pages |\n| `chart.js` | Charts and graphs | Dashboard |\n| `simplebar` | Custom scrollbars | Sidebar |\n| `@coreui/utils` | Utility functions | Theme switching |\n\n### Build Dependencies\n\n| Package | Purpose |\n|---------|---------|\n| `sass` | CSS preprocessing |\n| `sync-directory` | Copy `src/js`, `src/assets`, `src/views` into `dist/` |\n| `pug` | HTML templating |\n| `postcss` | CSS post-processing |\n| `autoprefixer` | Vendor prefix automation |\n| `browser-sync` | Development server |\n| `eslint` | JavaScript linting |\n| `stylelint` | CSS linting |\n\n## Browser Support\n\nDefined in `.browserslistrc`:\n\n```\n>= 0.5%\nlast 2 major versions\nnot dead\nChrome >= 60\nFirefox >= 60\nFirefox ESR\niOS >= 12\nSafari >= 12\nnot Explorer <= 11\n```\n\nModern browsers with native ES2015+ support - this is also why `src/js` ships untranspiled (see [Build Tools](#build-tools)).\n\n## Deployment\n\n### Static Hosting (Recommended)\n\n1. Run `npm run build`\n2. Deploy `dist/` folder to:\n   - Netlify\n   - Vercel\n   - GitHub Pages\n   - AWS S3 + CloudFront\n   - Any static file server\n\n### Traditional Web Server\n\n1. Run `npm run build`\n2. Copy `dist/` contents to web root\n3. Configure server to serve `index.html` as default\n4. Set proper MIME types for CSS/JS files\n\n### Docker (Optional)\n\n```dockerfile\nFROM nginx:alpine\nCOPY dist/ /usr/share/nginx/html/\nEXPOSE 80\n```\n\n## Performance Considerations\n\n### CSS Optimization\n- Sass compilation removes unused styles\n- PostCSS autoprefixer adds only necessary prefixes\n- Minification in production build\n- CSS is render-blocking (loaded in `<head>`)\n\n### JavaScript Optimization\n- No transpilation or minification step - files are copied as-is (see [Build Tools](#build-tools))\n- Files loaded as separate scripts (no bundler)\n- Deferred script loading where possible\n\n### Asset Optimization\n- SVG icons (scalable, small file size)\n- Favicon in multiple formats for compatibility\n- Images in `src/assets/` should be optimized before adding\n\n## Security Considerations\n\n### Content Security Policy (CSP)\nTemplate includes inline scripts and styles. For strict CSP:\n1. Extract inline scripts to external files\n2. Use nonces or hashes for required inline scripts\n3. Update CSP headers accordingly\n\n### XSS Prevention\n- Pug automatically escapes HTML by default\n- Use `!= html` only for trusted content\n- Sanitize user input on server-side (if adding backend)\n\n### Dependency Management\n- Regularly update npm dependencies\n- Run `npm audit` to check for vulnerabilities\n- Pin major versions in `package.json`\n\n## Extensibility\n\n### Adding New Pages\n\n1. Create `src/pug/views/my-page.pug`\n2. Extend layout: `extends ../_layout/default.pug`\n3. Override the `view` block (see [Block System](#pug-template-hierarchy)):\n   ```pug\n   block view\n     .container-lg.px-4\n       h1 My Page Title\n       p Page content here\n   ```\n4. Add an entry to `src/pug/_partials/sidebar-nav.pug` so the page is reachable from the sidebar\n5. Run `npm run pug` (or `npm start`) to compile\n6. Access at `/my-page.html`\n\n### Adding New Components\n\n1. Check CoreUI docs: https://coreui.io/bootstrap/docs/\n2. Copy component markup to Pug file\n3. Convert HTML to Pug syntax (use html2pug.com if needed)\n4. Import required JavaScript:\n   ```javascript\n   import { Modal } from '@coreui/coreui'\n   ```\n5. Initialize component in page-specific JS\n\n### Adding New Styles\n\n1. Edit `src/scss/style.scss` or create new partial\n2. Use Sass modules syntax to import CoreUI:\n   ```scss\n   @use \"@coreui/coreui/scss/coreui\" as * with (\n     $enable-deprecation-messages: false\n   );\n   ```\n   For CoreUI Pro projects:\n   ```scss\n   @use \"@coreui/coreui-pro/scss/coreui\" as * with (\n     $enable-deprecation-messages: false\n   );\n   ```\n3. Use CSS custom properties for theme compatibility\n4. Run `npm run css` to compile\n\n### Integrating Backend APIs\n\nThis template is frontend-only. To add backend:\n\n1. **Fetch API** for AJAX requests:\n   ```javascript\n   fetch('/api/endpoint')\n     .then(response => response.json())\n     .then(data => updateUI(data))\n   ```\n\n2. **Authentication**: Implement token-based auth\n   - Store JWT in localStorage/sessionStorage\n   - Add Authorization header to requests\n   - Redirect to login on 401 responses\n\n3. **State Management**: For complex apps, consider:\n   - Vanilla JS with custom events\n   - Lightweight state library (Zustand, Nano Stores)\n   - Full framework migration (React, Vue, etc.)\n\n## Common Issues and Solutions\n\n### Pug Compilation Errors\n- **Error**: \"Cannot find module\"\n  - **Fix**: Check Pug include/extend paths (relative to file)\n\n### Sass Compilation Errors\n- **Error**: \"Undefined variable\"\n  - **Fix**: Import Bootstrap/CoreUI variables before using\n\n### JavaScript Errors\n- **Error**: \"X is not defined\"\n  - **Fix**: Add `/* global X */` comment or import module\n\n### Live Reload Not Working\n- **Error**: Browser-sync not updating\n  - **Fix**: Check if `watch` scripts are running, restart `npm start`\n\n### Build Fails\n- **Error**: npm scripts fail\n  - **Fix**: Delete `node_modules/` and `dist/`, run `npm install`, then `npm run build`\n\n## Resources\n\n- **CoreUI Bootstrap Docs**: https://coreui.io/bootstrap/docs/\n- **Pug Documentation**: https://pugjs.org/\n- **Chart.js Documentation**: https://www.chartjs.org/\n- **Sass Documentation**: https://sass-lang.com/documentation/\n\n## Changelog\n\nSee [releases](https://github.com/coreui/coreui-free-bootstrap-admin-template/releases) for version history and updates.\n",".cursorrules":"# CoreUI Free Bootstrap Admin Template - AI Context\n\n## Project Overview\nThis is a Bootstrap 5 admin dashboard template built with CoreUI components. It uses Pug templating, Sass for styles, and vanilla JavaScript for interactivity.\n\n## Critical Rules\n\n### Component Library\n- **ALWAYS use CoreUI Bootstrap components**: https://coreui.io/bootstrap/docs/\n- **NEVER use Tailwind CSS** - this project uses Bootstrap 5 and custom Sass\n- Use CoreUI's CSS classes and JavaScript components from `@coreui/coreui` package\n- Reference the official CoreUI docs for component syntax and options\n\n### Technology Stack\n- **HTML Generation**: Pug templates (NOT raw HTML)\n- **Styling**: Sass/SCSS with Bootstrap 5 (NO Tailwind)\n- **JavaScript**: Vanilla JS with ES6 modules (NO frameworks like React/Vue)\n- **Build System**: npm scripts with Babel, PostCSS, and custom build scripts\n\n## Code Conventions\n\n### JavaScript\n- **No semicolons** - enforced by ESLint\n- **2-space indentation**\n- **ES6 modules** with import/export\n- **Strict mode** enabled\n- Use `/* global VariableName */` for external libraries\n- Follow XO ESLint config with Unicorn plugin rules\n\n### File Structure\n```\nsrc/\n├── js/          # JavaScript modules (keep small and focused)\n├── scss/        # Sass stylesheets (imports Bootstrap and CoreUI)\n├── pug/         # Pug templates (source of truth for HTML)\n│   ├── _layout/     # Base layouts\n│   ├── _partials/   # Reusable components\n│   ├── _mixins/     # Pug mixins\n│   └── views/       # Page templates\n├── assets/      # Images, icons, static files\n└── views/       # Compiled HTML (auto-generated, don't edit)\n```\n\n### Pug Templates\n- Use `extends ../_layout/default.pug` for new pages\n- Override blocks: `block content`, `block scripts`\n- Use mixins from `_mixins/` for common patterns\n- Follow existing naming conventions for consistency\n\n### CSS/Sass\n- Use Bootstrap utilities first before custom CSS\n- Use CSS custom properties (CSS variables) for theming\n- Use Bootstrap/CoreUI class naming conventions (e.g., `.sidebar`, `.header`, `.card-title`)\n- Support dark mode via `[data-coreui-theme=\"dark\"]`\n- **Never use**: `border-radius`, `transition`, `calc()` directly (Stylelint enforced)\n\n### Naming Conventions\n- **Files**: kebab-case (e.g., `color-modes.js`, `_header.pug`)\n- **CSS classes**: Bootstrap/CoreUI conventions (e.g., `.btn-primary`, `.card-header`)\n- **JavaScript variables**: camelCase\n- **Constants**: UPPER_SNAKE_CASE\n\n## Development Workflow\n\n### Adding New Pages\n1. Create Pug template in `src/pug/views/`\n2. Extend base layout: `extends ../_layout/default.pug`\n3. Add page-specific styles in `src/scss/` if needed\n4. Add page-specific JS in `src/js/` if needed\n5. Run `npm start` to compile and preview\n\n### Adding New Components\n1. **First check CoreUI docs**: https://coreui.io/bootstrap/docs/\n2. Use CoreUI component markup in Pug files\n3. Import required CoreUI JS modules if needed\n4. Style using CoreUI/Bootstrap classes, not custom CSS\n5. Create Pug mixin in `src/pug/_mixins/` for reusable patterns\n\n### Build Commands\n- `npm start` - Development with live reload\n- `npm run build` - Production build\n- `npm run watch-css` - Watch Sass changes\n- `npm run watch-js` - Watch JavaScript changes\n- `npm run watch-pug` - Watch Pug changes\n\n## Code Quality\n\n### Linting\n- **JavaScript**: ESLint with XO config (flat config format)\n- **Styles**: Stylelint with Bootstrap config\n- **Formatting**: Prettier for HTML output\n- Run `npm run lint` before committing\n\n### Comments and Documentation\n- **JSDoc required** for all functions with parameters\n- Explain \"why\", not \"what\"\n- Document complex template logic in Pug files\n- Add file-level comments explaining module purpose\n\n### Git Commits\nFollow semantic commit format:\n- `feat:` - New feature\n- `fix:` - Bug fix\n- `docs:` - Documentation changes\n- `style:` - Code style changes (formatting)\n- `refactor:` - Code refactoring\n- `test:` - Test additions/changes\n- `chore:` - Build/tooling changes\n\n## Common Patterns\n\n### Chart Integration\n```javascript\n/* global Chart */\nimport { getStyle } from '@coreui/utils'\n\nconst chart = new Chart(ctx, {\n  type: 'line',\n  data: { /* ... */ },\n  options: { /* ... */ }\n})\n```\n\n### Theme Switching\n```javascript\nimport { ColorModeStorageManager } from '@coreui/coreui/js/color-modes'\n\ndocument.addEventListener('ColorSchemeChange', () => {\n  // React to theme changes\n})\n```\n\n### Pug Mixin Usage\n```pug\ninclude _mixins/breadcrumb\n+breadcrumb(['Home', 'Components', 'Buttons'])\n```\n\n## AI Assistance Guidelines\n\n### When AI Should\n- Use CoreUI Bootstrap components from official docs\n- Generate Pug templates, not raw HTML\n- Follow existing patterns in the codebase\n- Add JSDoc comments to new JavaScript functions\n- Respect ESLint/Stylelint rules\n- Suggest npm scripts for tasks\n\n### When AI Should NOT\n- Use Tailwind CSS classes\n- Use React/Vue/Angular components\n- Edit compiled files in `dist/` or `src/views/`\n- Add unnecessary dependencies\n- Break existing build pipeline\n- Ignore linting errors\n\n## External Dependencies\n\n### Core Libraries\n- `@coreui/coreui` - CoreUI component library\n- `chart.js` - Charts and graphs\n- `simplebar` - Custom scrollbars\n\n### Build Tools\n- `sass` - CSS preprocessor\n- `@babel/core` - JavaScript transpiler\n- `pug` - HTML templating\n- `postcss` - CSS post-processing\n- `browser-sync` - Live reload server\n\n## Browser Support\nDefined in `.browserslistrc`:\n- Last 1 major version of modern browsers\n- Chrome, Firefox, Edge, Safari\n- iOS Safari, Chrome Android\n\n## Resources\n- CoreUI Docs: https://coreui.io/bootstrap/docs/\n- Chart.js Docs: https://www.chartjs.org/\n- Pug Docs: https://pugjs.org/\n\n## Project Maintainer Notes\n- License: MIT\n- Version: 5.5.0\n- Repository: https://github.com/coreui/coreui-free-bootstrap-admin-template\n"},"files":{"ARCHITECTURE.md":"# Architecture Documentation\n\n## Project Purpose\n\nCoreUI Free Bootstrap Admin Template is a professional admin dashboard template built on Bootstrap 5 and CoreUI components. It provides a ready-to-use foundation for building admin panels, dashboards, and web applications with a clean, modern interface.\n\n**Key Characteristics:**\n- Server-side templating approach (Pug → HTML)\n- Bootstrap 5 + CoreUI component library\n- Vanilla JavaScript (no framework dependencies)\n- Multi-page application (MPA) architecture\n- Static file generation with build-time compilation\n\n## High-Level Architecture\n\n```\n┌─────────────────────────────────────────────────────┐\n│                   Source Files                      │\n│  ┌──────────┐  ┌──────────┐  ┌──────────┐           │\n│  │   Pug    │  │   Sass   │  │    JS    │           │\n│  │Templates │  │  Styles  │  │ Modules  │           │\n│  └────┬─────┘  └────┬─────┘  └────┬─────┘           │\n│       │             │             │                 │\n└───────┼─────────────┼─────────────┼─────────────────┘\n        │             │             │\n        ▼             ▼             ▼\n┌─────────────────────────────────────────────────────┐\n│                  Build Pipeline                     │\n│  ┌──────────┐  ┌──────────┐  ┌──────────┐           │\n│  │   Pug    │  │PostCSS + │  │ syncdir  │           │\n│  │Compiler  │  │  Sass    │  │(copy JS) │           │\n│  └────┬─────┘  └────┬─────┘  └────┬─────┘           │\n│       │             │             │                 │\n└───────┼─────────────┼─────────────┼─────────────────┘\n        │             │             │\n        ▼             ▼             ▼\n┌─────────────────────────────────────────────────────┐\n│                 Distribution Files                  │\n│  ┌──────────┐  ┌──────────┐  ┌──────────┐           │\n│  │   HTML   │  │   CSS    │  │    JS    │           │\n│  │  Files   │  │ (minified)│  │(bundled) │          │\n│  └──────────┘  └──────────┘  └──────────┘           │\n│         (served via browser-sync or web server)     │\n└─────────────────────────────────────────────────────┘\n```\n\n## Technology Stack\n\n### Frontend\n- **HTML Generation**: Pug 3.0.3 (template engine)\n- **CSS Framework**: Bootstrap 5.3.x\n- **Component Library**: CoreUI 5.x (@coreui/coreui)\n- **Icons**: CoreUI Icons (@coreui/icons)\n- **JavaScript**: Vanilla ES6+ (no framework)\n- **Charts**: Chart.js 4.x\n- **Scrollbars**: SimpleBar 6.x\n\n### Build Tools\n- **Package Manager**: npm\n- **CSS Processing**: Sass 1.102.x → PostCSS → Autoprefixer\n- **JS**: plain ES2015+, copied as-is via `sync-directory` (no transpilation - the declared browser targets already support the syntax used, see [Browser Support](#browser-support))\n- **Task Runner**: npm scripts with npm-run-all\n- **File Watching**: Nodemon\n- **Live Server**: Browser-sync 3.0.4\n\n### Code Quality\n- **Linting**: ESLint 9.x (flat config) with XO + Unicorn\n- **Style Linting**: Stylelint 16.x with Bootstrap config\n- **Formatting**: Prettier 3.9.x\n- **Editor Config**: .editorconfig for consistency\n\n## Directory Structure\n\n```\ncoreui-free-bootstrap-admin-template/\n│\n├── src/                          # Source files (edit these)\n│   ├── pug/                      # Pug templates (HTML source)\n│   │   ├── _layout/              # Base layout templates\n│   │   │   ├── default.pug       # Main layout with sidebar/header\n│   │   │   └── pages.pug         # Standalone pages layout (auth, errors)\n│   │   ├── _partials/            # Reusable components\n│   │   │   ├── banner.pug        # Top announcement banner\n│   │   │   ├── head.pug          # HTML <head> section\n│   │   │   ├── header.pug        # Top navigation bar\n│   │   │   ├── sidebar.pug       # Left sidebar wrapper\n│   │   │   ├── sidebar-nav.pug   # Sidebar navigation items (data-driven)\n│   │   │   ├── footer.pug        # Page footer\n│   │   │   ├── scripts.pug       # Common script includes\n│   │   │   └── docs-icons.pug    # Icon documentation helpers\n│   │   ├── _mixins/              # Pug helper mixins\n│   │   │   ├── breadcrumb.pug    # Breadcrumb generator\n│   │   │   ├── callout.pug       # Alert/callout boxes\n│   │   │   ├── callout-custom.pug # Custom callout variant\n│   │   │   ├── docs-components.pug # Docs component helpers\n│   │   │   ├── example.pug       # Code example displays\n│   │   │   └── inline-svg.pug    # Inline SVG helper\n│   │   └── views/                # Page templates\n│   │       ├── index.pug         # Main dashboard page\n│   │       ├── blank.pug         # Blank page template\n│   │       ├── charts.pug        # Charts page\n│   │       ├── widgets.pug       # Widgets page\n│   │       ├── authentication/   # Auth pages (login, register, etc.)\n│   │       ├── components/       # UI components (buttons, modals, etc.)\n│   │       ├── error-pages/      # Error pages (404, 500)\n│   │       ├── forms/            # Form components\n│   │       └── icons/            # Icon libraries\n│   │\n│   ├── scss/                     # Sass stylesheets\n│   │   ├── style.scss            # Main stylesheet entry\n│   │   ├── style-rtl.scss        # RTL (right-to-left) styles\n│   │   └── examples.scss         # Demo/example page styles\n│   │\n│   ├── js/                       # JavaScript modules\n│   │   ├── main.js               # Main entry point\n│   │   ├── charts.js             # Chart.js configurations\n│   │   ├── color-modes.js        # Dark/light theme switcher\n│   │   ├── config.js             # App configuration / shared settings\n│   │   ├── tooltips.js           # Tooltip initialization\n│   │   ├── popovers.js           # Popover initialization\n│   │   ├── toasts.js             # Toast notification initialization\n│   │   └── widgets.js            # Widgets page charts\n│   │\n│   ├── assets/                   # Static assets\n│   │   ├── brand/                # Logo files\n│   │   ├── favicon/              # Favicon files\n│   │   └── img/                  # Images\n│   │\n│   └── views/                    # Compiled HTML (auto-generated)\n│       └── *.html                # Do NOT edit these manually\n│\n├── dist/                         # Production build output\n│   ├── css/                      # Minified CSS\n│   ├── js/                       # Synced JS (copied as-is, no transform)\n│   ├── assets/                   # Copied assets\n│   ├── vendors/                  # Third-party libraries\n│   └── *.html                    # Production HTML files\n│\n├── build/                        # Build scripts\n│   ├── pug.mjs                   # Pug compilation script\n│   ├── postcss.config.mjs        # PostCSS configuration\n│   ├── vendors.mjs               # Vendor file bundling\n│   └── format-html.mjs           # HTML formatting/prettifying\n│\n├── node_modules/                 # npm dependencies (ignored)\n│\n└── Configuration files\n    ├── package.json              # Dependencies and scripts\n    ├── .editorconfig             # Editor settings\n    ├── eslint.config.mjs         # ESLint flat config\n    ├── .prettierrc.json          # Prettier formatting\n    ├── .stylelintrc              # Stylelint rules\n    ├── .browserslistrc           # Target browsers\n    └── .cursorrules              # AI context (Cursor IDE)\n```\n\n## Build Pipeline Details\n\n### Development Mode (`npm start`)\n\n1. **Clean**: Remove old compiled files\n2. **Compile Pug**: `src/pug/**/*.pug` → `src/views/*.html`\n3. **Compile Sass**: `src/scss/*.scss` → `dist/css/*.css` (expanded, autoprefixed)\n4. **Sync JS**: `src/js/*.js` → `dist/js/*.js` (copied as-is via `sync-directory`, no transform)\n5. **Copy Assets**: `src/assets/**/*` → `dist/assets/`\n6. **Build Vendors**: Bundle third-party libraries\n7. **Watch Files**: Monitor changes and recompile\n8. **Browser-sync**: Live reload server on http://localhost:3000\n\n### Production Build (`npm run build`)\n\n1. **All development steps**\n2. **Minify CSS**: Compress stylesheets with clean-css-cli\n3. **JS**: No separate minify step - shipped as synced source\n4. **Optimize Assets**: Copy optimized files\n5. **Generate zip**: Create distribution package\n\n### File Watching\n\n```\nnpm run watch          # Watch all file types\nnpm run watch-pug      # Watch Pug templates only\nnpm run watch-css      # Watch Sass files only\nnpm run watch-js       # Watch JavaScript files only\n```\n\nEach watch task uses **nodemon** to monitor file changes and trigger appropriate compilation.\n\n## Data Flow\n\n### Page Rendering Flow\n\n```\n1. Browser Request\n   └─> /index.html\n\n2. Server Response\n   └─> Serve dist/index.html (static file)\n\n3. HTML Loads Resources\n   ├─> dist/css/style.css (Bootstrap + CoreUI + custom styles)\n   ├─> dist/js/main.js (app initialization)\n   └─> dist/vendors/*.js (Chart.js, SimpleBar, etc.)\n\n4. JavaScript Execution\n   ├─> Initialize CoreUI components\n   ├─> Set up event listeners\n   ├─> Configure charts (if on dashboard)\n   └─> Enable tooltips/popovers\n\n5. User Interaction\n   └─> JavaScript handles UI updates (no page reload)\n```\n\n### Theme Switching Flow\n\n```\n1. User clicks theme toggle button\n   └─> color-modes.js listens for click\n\n2. ColorModeStorageManager updates preference\n   ├─> Save to localStorage\n   └─> Update [data-coreui-theme] attribute\n\n3. CSS custom properties respond\n   └─> Variables change (--cui-primary-bg, --cui-text-color, etc.)\n\n4. ColorSchemeChange event fires\n   └─> Charts re-render with new theme colors\n```\n\n### Chart Rendering Flow\n\n```\n1. charts.js module loads\n   └─> import Chart from 'chart.js/auto'\n\n2. DOM ready\n   └─> Find chart canvas elements\n\n3. Fetch data (or use inline data)\n   └─> Random data generator for demo\n\n4. Create Chart.js instance\n   ├─> Configure chart type (line, bar, pie, etc.)\n   ├─> Apply theme colors from CSS variables\n   └─> Set responsive options\n\n5. Theme changes\n   └─> Re-initialize charts with new colors\n```\n\n## Component Organization\n\n### Pug Template Hierarchy\n\n```\ndefault.pug (main layout — dashboard/component pages)\n├─> sidebar.pug (side navigation)\n│   └─> sidebar-nav.pug (data-driven nav items)\n├─> header.pug (top navigation bar)\n│   └─> block breadcrumb\n├─> block canonical / block styles\n├─> block view\n│   └─> index.pug / components/*.pug / etc. (page content)\n└─> footer.pug (page footer)\n    └─> scripts.pug (common script includes)\n        └─> block scripts / block js\n\npages.pug (standalone layout — auth & error pages)\n├─> block styles\n└─> block view\n    └─> authentication/*.pug / error-pages/*.pug\n```\n\n**Block System:**\n- `block view`: Main page content area (both layouts)\n- `block canonical`: `<link rel=\"canonical\">` override (`default.pug` only)\n- `block breadcrumb`: Breadcrumb trail, declared inside `header.pug` (`default.pug` only)\n- `block scripts` / `block js`: Page-specific script includes, declared inside `scripts.pug`\n- Each view extends a layout and overrides only the blocks it needs\n\n### CSS Architecture\n\n```\nstyle.scss\n├─> Import Bootstrap 5\n├─> Import CoreUI components\n├─> Import custom variables\n└─> Import custom component styles\n\nTheme System:\n[data-coreui-theme=\"light\"]  # Light mode (default)\n[data-coreui-theme=\"dark\"]   # Dark mode\n[data-coreui-theme=\"auto\"]   # System preference\n```\n\n**CSS Custom Properties:**\n- `--cui-primary`, `--cui-secondary`, etc. (colors)\n- `--cui-bg`, `--cui-text-color` (backgrounds/text)\n- `--cui-border-color`, `--cui-shadow` (UI elements)\n\n### JavaScript Module Pattern\n\nEach JS file in `src/js/` is an ES6 module:\n\n```javascript\n// Import dependencies\nimport { Something } from '@coreui/coreui'\n\n// Define functionality\nconst doSomething = () => { /* ... */ }\n\n// Initialize on DOM ready\ndocument.addEventListener('DOMContentLoaded', () => {\n  doSomething()\n})\n\n// Export if needed (most files use side effects only)\n```\n\n## Key Dependencies\n\n### Runtime Dependencies\n\n| Package | Purpose | Used In |\n|---------|---------|---------|\n| `@coreui/coreui` | UI component library | All pages |\n| `@coreui/icons` | Icon library | Icon pages |\n| `chart.js` | Charts and graphs | Dashboard |\n| `simplebar` | Custom scrollbars | Sidebar |\n| `@coreui/utils` | Utility functions | Theme switching |\n\n### Build Dependencies\n\n| Package | Purpose |\n|---------|---------|\n| `sass` | CSS preprocessing |\n| `sync-directory` | Copy `src/js`, `src/assets`, `src/views` into `dist/` |\n| `pug` | HTML templating |\n| `postcss` | CSS post-processing |\n| `autoprefixer` | Vendor prefix automation |\n| `browser-sync` | Development server |\n| `eslint` | JavaScript linting |\n| `stylelint` | CSS linting |\n\n## Browser Support\n\nDefined in `.browserslistrc`:\n\n```\n>= 0.5%\nlast 2 major versions\nnot dead\nChrome >= 60\nFirefox >= 60\nFirefox ESR\niOS >= 12\nSafari >= 12\nnot Explorer <= 11\n```\n\nModern browsers with native ES2015+ support - this is also why `src/js` ships untranspiled (see [Build Tools](#build-tools)).\n\n## Deployment\n\n### Static Hosting (Recommended)\n\n1. Run `npm run build`\n2. Deploy `dist/` folder to:\n   - Netlify\n   - Vercel\n   - GitHub Pages\n   - AWS S3 + CloudFront\n   - Any static file server\n\n### Traditional Web Server\n\n1. Run `npm run build`\n2. Copy `dist/` contents to web root\n3. Configure server to serve `index.html` as default\n4. Set proper MIME types for CSS/JS files\n\n### Docker (Optional)\n\n```dockerfile\nFROM nginx:alpine\nCOPY dist/ /usr/share/nginx/html/\nEXPOSE 80\n```\n\n## Performance Considerations\n\n### CSS Optimization\n- Sass compilation removes unused styles\n- PostCSS autoprefixer adds only necessary prefixes\n- Minification in production build\n- CSS is render-blocking (loaded in `<head>`)\n\n### JavaScript Optimization\n- No transpilation or minification step - files are copied as-is (see [Build Tools](#build-tools))\n- Files loaded as separate scripts (no bundler)\n- Deferred script loading where possible\n\n### Asset Optimization\n- SVG icons (scalable, small file size)\n- Favicon in multiple formats for compatibility\n- Images in `src/assets/` should be optimized before adding\n\n## Security Considerations\n\n### Content Security Policy (CSP)\nTemplate includes inline scripts and styles. For strict CSP:\n1. Extract inline scripts to external files\n2. Use nonces or hashes for required inline scripts\n3. Update CSP headers accordingly\n\n### XSS Prevention\n- Pug automatically escapes HTML by default\n- Use `!= html` only for trusted content\n- Sanitize user input on server-side (if adding backend)\n\n### Dependency Management\n- Regularly update npm dependencies\n- Run `npm audit` to check for vulnerabilities\n- Pin major versions in `package.json`\n\n## Extensibility\n\n### Adding New Pages\n\n1. Create `src/pug/views/my-page.pug`\n2. Extend layout: `extends ../_layout/default.pug`\n3. Override the `view` block (see [Block System](#pug-template-hierarchy)):\n   ```pug\n   block view\n     .container-lg.px-4\n       h1 My Page Title\n       p Page content here\n   ```\n4. Add an entry to `src/pug/_partials/sidebar-nav.pug` so the page is reachable from the sidebar\n5. Run `npm run pug` (or `npm start`) to compile\n6. Access at `/my-page.html`\n\n### Adding New Components\n\n1. Check CoreUI docs: https://coreui.io/bootstrap/docs/\n2. Copy component markup to Pug file\n3. Convert HTML to Pug syntax (use html2pug.com if needed)\n4. Import required JavaScript:\n   ```javascript\n   import { Modal } from '@coreui/coreui'\n   ```\n5. Initialize component in page-specific JS\n\n### Adding New Styles\n\n1. Edit `src/scss/style.scss` or create new partial\n2. Use Sass modules syntax to import CoreUI:\n   ```scss\n   @use \"@coreui/coreui/scss/coreui\" as * with (\n     $enable-deprecation-messages: false\n   );\n   ```\n   For CoreUI Pro projects:\n   ```scss\n   @use \"@coreui/coreui-pro/scss/coreui\" as * with (\n     $enable-deprecation-messages: false\n   );\n   ```\n3. Use CSS custom properties for theme compatibility\n4. Run `npm run css` to compile\n\n### Integrating Backend APIs\n\nThis template is frontend-only. To add backend:\n\n1. **Fetch API** for AJAX requests:\n   ```javascript\n   fetch('/api/endpoint')\n     .then(response => response.json())\n     .then(data => updateUI(data))\n   ```\n\n2. **Authentication**: Implement token-based auth\n   - Store JWT in localStorage/sessionStorage\n   - Add Authorization header to requests\n   - Redirect to login on 401 responses\n\n3. **State Management**: For complex apps, consider:\n   - Vanilla JS with custom events\n   - Lightweight state library (Zustand, Nano Stores)\n   - Full framework migration (React, Vue, etc.)\n\n## Common Issues and Solutions\n\n### Pug Compilation Errors\n- **Error**: \"Cannot find module\"\n  - **Fix**: Check Pug include/extend paths (relative to file)\n\n### Sass Compilation Errors\n- **Error**: \"Undefined variable\"\n  - **Fix**: Import Bootstrap/CoreUI variables before using\n\n### JavaScript Errors\n- **Error**: \"X is not defined\"\n  - **Fix**: Add `/* global X */` comment or import module\n\n### Live Reload Not Working\n- **Error**: Browser-sync not updating\n  - **Fix**: Check if `watch` scripts are running, restart `npm start`\n\n### Build Fails\n- **Error**: npm scripts fail\n  - **Fix**: Delete `node_modules/` and `dist/`, run `npm install`, then `npm run build`\n\n## Resources\n\n- **CoreUI Bootstrap Docs**: https://coreui.io/bootstrap/docs/\n- **Pug Documentation**: https://pugjs.org/\n- **Chart.js Documentation**: https://www.chartjs.org/\n- **Sass Documentation**: https://sass-lang.com/documentation/\n\n## Changelog\n\nSee [releases](https://github.com/coreui/coreui-free-bootstrap-admin-template/releases) for version history and updates.\n",".cursorrules":"# CoreUI Free Bootstrap Admin Template - AI Context\n\n## Project Overview\nThis is a Bootstrap 5 admin dashboard template built with CoreUI components. It uses Pug templating, Sass for styles, and vanilla JavaScript for interactivity.\n\n## Critical Rules\n\n### Component Library\n- **ALWAYS use CoreUI Bootstrap components**: https://coreui.io/bootstrap/docs/\n- **NEVER use Tailwind CSS** - this project uses Bootstrap 5 and custom Sass\n- Use CoreUI's CSS classes and JavaScript components from `@coreui/coreui` package\n- Reference the official CoreUI docs for component syntax and options\n\n### Technology Stack\n- **HTML Generation**: Pug templates (NOT raw HTML)\n- **Styling**: Sass/SCSS with Bootstrap 5 (NO Tailwind)\n- **JavaScript**: Vanilla JS with ES6 modules (NO frameworks like React/Vue)\n- **Build System**: npm scripts with Babel, PostCSS, and custom build scripts\n\n## Code Conventions\n\n### JavaScript\n- **No semicolons** - enforced by ESLint\n- **2-space indentation**\n- **ES6 modules** with import/export\n- **Strict mode** enabled\n- Use `/* global VariableName */` for external libraries\n- Follow XO ESLint config with Unicorn plugin rules\n\n### File Structure\n```\nsrc/\n├── js/          # JavaScript modules (keep small and focused)\n├── scss/        # Sass stylesheets (imports Bootstrap and CoreUI)\n├── pug/         # Pug templates (source of truth for HTML)\n│   ├── _layout/     # Base layouts\n│   ├── _partials/   # Reusable components\n│   ├── _mixins/     # Pug mixins\n│   └── views/       # Page templates\n├── assets/      # Images, icons, static files\n└── views/       # Compiled HTML (auto-generated, don't edit)\n```\n\n### Pug Templates\n- Use `extends ../_layout/default.pug` for new pages\n- Override blocks: `block content`, `block scripts`\n- Use mixins from `_mixins/` for common patterns\n- Follow existing naming conventions for consistency\n\n### CSS/Sass\n- Use Bootstrap utilities first before custom CSS\n- Use CSS custom properties (CSS variables) for theming\n- Use Bootstrap/CoreUI class naming conventions (e.g., `.sidebar`, `.header`, `.card-title`)\n- Support dark mode via `[data-coreui-theme=\"dark\"]`\n- **Never use**: `border-radius`, `transition`, `calc()` directly (Stylelint enforced)\n\n### Naming Conventions\n- **Files**: kebab-case (e.g., `color-modes.js`, `_header.pug`)\n- **CSS classes**: Bootstrap/CoreUI conventions (e.g., `.btn-primary`, `.card-header`)\n- **JavaScript variables**: camelCase\n- **Constants**: UPPER_SNAKE_CASE\n\n## Development Workflow\n\n### Adding New Pages\n1. Create Pug template in `src/pug/views/`\n2. Extend base layout: `extends ../_layout/default.pug`\n3. Add page-specific styles in `src/scss/` if needed\n4. Add page-specific JS in `src/js/` if needed\n5. Run `npm start` to compile and preview\n\n### Adding New Components\n1. **First check CoreUI docs**: https://coreui.io/bootstrap/docs/\n2. Use CoreUI component markup in Pug files\n3. Import required CoreUI JS modules if needed\n4. Style using CoreUI/Bootstrap classes, not custom CSS\n5. Create Pug mixin in `src/pug/_mixins/` for reusable patterns\n\n### Build Commands\n- `npm start` - Development with live reload\n- `npm run build` - Production build\n- `npm run watch-css` - Watch Sass changes\n- `npm run watch-js` - Watch JavaScript changes\n- `npm run watch-pug` - Watch Pug changes\n\n## Code Quality\n\n### Linting\n- **JavaScript**: ESLint with XO config (flat config format)\n- **Styles**: Stylelint with Bootstrap config\n- **Formatting**: Prettier for HTML output\n- Run `npm run lint` before committing\n\n### Comments and Documentation\n- **JSDoc required** for all functions with parameters\n- Explain \"why\", not \"what\"\n- Document complex template logic in Pug files\n- Add file-level comments explaining module purpose\n\n### Git Commits\nFollow semantic commit format:\n- `feat:` - New feature\n- `fix:` - Bug fix\n- `docs:` - Documentation changes\n- `style:` - Code style changes (formatting)\n- `refactor:` - Code refactoring\n- `test:` - Test additions/changes\n- `chore:` - Build/tooling changes\n\n## Common Patterns\n\n### Chart Integration\n```javascript\n/* global Chart */\nimport { getStyle } from '@coreui/utils'\n\nconst chart = new Chart(ctx, {\n  type: 'line',\n  data: { /* ... */ },\n  options: { /* ... */ }\n})\n```\n\n### Theme Switching\n```javascript\nimport { ColorModeStorageManager } from '@coreui/coreui/js/color-modes'\n\ndocument.addEventListener('ColorSchemeChange', () => {\n  // React to theme changes\n})\n```\n\n### Pug Mixin Usage\n```pug\ninclude _mixins/breadcrumb\n+breadcrumb(['Home', 'Components', 'Buttons'])\n```\n\n## AI Assistance Guidelines\n\n### When AI Should\n- Use CoreUI Bootstrap components from official docs\n- Generate Pug templates, not raw HTML\n- Follow existing patterns in the codebase\n- Add JSDoc comments to new JavaScript functions\n- Respect ESLint/Stylelint rules\n- Suggest npm scripts for tasks\n\n### When AI Should NOT\n- Use Tailwind CSS classes\n- Use React/Vue/Angular components\n- Edit compiled files in `dist/` or `src/views/`\n- Add unnecessary dependencies\n- Break existing build pipeline\n- Ignore linting errors\n\n## External Dependencies\n\n### Core Libraries\n- `@coreui/coreui` - CoreUI component library\n- `chart.js` - Charts and graphs\n- `simplebar` - Custom scrollbars\n\n### Build Tools\n- `sass` - CSS preprocessor\n- `@babel/core` - JavaScript transpiler\n- `pug` - HTML templating\n- `postcss` - CSS post-processing\n- `browser-sync` - Live reload server\n\n## Browser Support\nDefined in `.browserslistrc`:\n- Last 1 major version of modern browsers\n- Chrome, Firefox, Edge, Safari\n- iOS Safari, Chrome Android\n\n## Resources\n- CoreUI Docs: https://coreui.io/bootstrap/docs/\n- Chart.js Docs: https://www.chartjs.org/\n- Pug Docs: https://pugjs.org/\n\n## Project Maintainer Notes\n- License: MIT\n- Version: 5.5.0\n- Repository: https://github.com/coreui/coreui-free-bootstrap-admin-template\n"},"items":[{"name":"ARCHITECTURE.md","path":"ARCHITECTURE.md","rawUrl":"https://raw.githubusercontent.com/coreui/coreui-free-bootstrap-admin-template/HEAD/ARCHITECTURE.md","title":"System Architecture & Module Boundaries","category":"project-spec","format":"markdown","content":"# Architecture Documentation\n\n## Project Purpose\n\nCoreUI Free Bootstrap Admin Template is a professional admin dashboard template built on Bootstrap 5 and CoreUI components. It provides a ready-to-use foundation for building admin panels, dashboards, and web applications with a clean, modern interface.\n\n**Key Characteristics:**\n- Server-side templating approach (Pug → HTML)\n- Bootstrap 5 + CoreUI component library\n- Vanilla JavaScript (no framework dependencies)\n- Multi-page application (MPA) architecture\n- Static file generation with build-time compilation\n\n## High-Level Architecture\n\n```\n┌─────────────────────────────────────────────────────┐\n│                   Source Files                      │\n│  ┌──────────┐  ┌──────────┐  ┌──────────┐           │\n│  │   Pug    │  │   Sass   │  │    JS    │           │\n│  │Templates │  │  Styles  │  │ Modules  │           │\n│  └────┬─────┘  └────┬─────┘  └────┬─────┘           │\n│       │             │             │                 │\n└───────┼─────────────┼─────────────┼─────────────────┘\n        │             │             │\n        ▼             ▼             ▼\n┌─────────────────────────────────────────────────────┐\n│                  Build Pipeline                     │\n│  ┌──────────┐  ┌──────────┐  ┌──────────┐           │\n│  │   Pug    │  │PostCSS + │  │ syncdir  │           │\n│  │Compiler  │  │  Sass    │  │(copy JS) │           │\n│  └────┬─────┘  └────┬─────┘  └────┬─────┘           │\n│       │             │             │                 │\n└───────┼─────────────┼─────────────┼─────────────────┘\n        │             │             │\n        ▼             ▼             ▼\n┌─────────────────────────────────────────────────────┐\n│                 Distribution Files                  │\n│  ┌──────────┐  ┌──────────┐  ┌──────────┐           │\n│  │   HTML   │  │   CSS    │  │    JS    │           │\n│  │  Files   │  │ (minified)│  │(bundled) │          │\n│  └──────────┘  └──────────┘  └──────────┘           │\n│         (served via browser-sync or web server)     │\n└─────────────────────────────────────────────────────┘\n```\n\n## Technology Stack\n\n### Frontend\n- **HTML Generation**: Pug 3.0.3 (template engine)\n- **CSS Framework**: Bootstrap 5.3.x\n- **Component Library**: CoreUI 5.x (@coreui/coreui)\n- **Icons**: CoreUI Icons (@coreui/icons)\n- **JavaScript**: Vanilla ES6+ (no framework)\n- **Charts**: Chart.js 4.x\n- **Scrollbars**: SimpleBar 6.x\n\n### Build Tools\n- **Package Manager**: npm\n- **CSS Processing**: Sass 1.102.x → PostCSS → Autoprefixer\n- **JS**: plain ES2015+, copied as-is via `sync-directory` (no transpilation - the declared browser targets already support the syntax used, see [Browser Support](#browser-support))\n- **Task Runner**: npm scripts with npm-run-all\n- **File Watching**: Nodemon\n- **Live Server**: Browser-sync 3.0.4\n\n### Code Quality\n- **Linting**: ESLint 9.x (flat config) with XO + Unicorn\n- **Style Linting**: Stylelint 16.x with Bootstrap config\n- **Formatting**: Prettier 3.9.x\n- **Editor Config**: .editorconfig for consistency\n\n## Directory Structure\n\n```\ncoreui-free-bootstrap-admin-template/\n│\n├── src/                          # Source files (edit these)\n│   ├── pug/                      # Pug templates (HTML source)\n│   │   ├── _layout/              # Base layout templates\n│   │   │   ├── default.pug       # Main layout with sidebar/header\n│   │   │   └── pages.pug         # Standalone pages layout (auth, errors)\n│   │   ├── _partials/            # Reusable components\n│   │   │   ├── banner.pug        # Top announcement banner\n│   │   │   ├── head.pug          # HTML <head> section\n│   │   │   ├── header.pug        # Top navigation bar\n│   │   │   ├── sidebar.pug       # Left sidebar wrapper\n│   │   │   ├── sidebar-nav.pug   # Sidebar navigation items (data-driven)\n│   │   │   ├── footer.pug        # Page footer\n│   │   │   ├── scripts.pug       # Common script includes\n│   │   │   └── docs-icons.pug    # Icon documentation helpers\n│   │   ├── _mixins/              # Pug helper mixins\n│   │   │   ├── breadcrumb.pug    # Breadcrumb generator\n│   │   │   ├── callout.pug       # Alert/callout boxes\n│   │   │   ├── callout-custom.pug # Custom callout variant\n│   │   │   ├── docs-components.pug # Docs component helpers\n│   │   │   ├── example.pug       # Code example displays\n│   │   │   └── inline-svg.pug    # Inline SVG helper\n│   │   └── views/                # Page templates\n│   │       ├── index.pug         # Main dashboard page\n│   │       ├── blank.pug         # Blank page template\n│   │       ├── charts.pug        # Charts page\n│   │       ├── widgets.pug       # Widgets page\n│   │       ├── authentication/   # Auth pages (login, register, etc.)\n│   │       ├── components/       # UI components (buttons, modals, etc.)\n│   │       ├── error-pages/      # Error pages (404, 500)\n│   │       ├── forms/            # Form components\n│   │       └── icons/            # Icon libraries\n│   │\n│   ├── scss/                     # Sass stylesheets\n│   │   ├── style.scss            # Main stylesheet entry\n│   │   ├── style-rtl.scss        # RTL (right-to-left) styles\n│   │   └── examples.scss         # Demo/example page styles\n│   │\n│   ├── js/                       # JavaScript modules\n│   │   ├── main.js               # Main entry point\n│   │   ├── charts.js             # Chart.js configurations\n│   │   ├── color-modes.js        # Dark/light theme switcher\n│   │   ├── config.js             # App configuration / shared settings\n│   │   ├── tooltips.js           # Tooltip initialization\n│   │   ├── popovers.js           # Popover initialization\n│   │   ├── toasts.js             # Toast notification initialization\n│   │   └── widgets.js            # Widgets page charts\n│   │\n│   ├── assets/                   # Static assets\n│   │   ├── brand/                # Logo files\n│   │   ├── favicon/              # Favicon files\n│   │   └── img/                  # Images\n│   │\n│   └── views/                    # Compiled HTML (auto-generated)\n│       └── *.html                # Do NOT edit these manually\n│\n├── dist/                         # Production build output\n│   ├── css/                      # Minified CSS\n│   ├── js/                       # Synced JS (copied as-is, no transform)\n│   ├── assets/                   # Copied assets\n│   ├── vendors/                  # Third-party libraries\n│   └── *.html                    # Production HTML files\n│\n├── build/                        # Build scripts\n│   ├── pug.mjs                   # Pug compilation script\n│   ├── postcss.config.mjs        # PostCSS configuration\n│   ├── vendors.mjs               # Vendor file bundling\n│   └── format-html.mjs           # HTML formatting/prettifying\n│\n├── node_modules/                 # npm dependencies (ignored)\n│\n└── Configuration files\n    ├── package.json              # Dependencies and scripts\n    ├── .editorconfig             # Editor settings\n    ├── eslint.config.mjs         # ESLint flat config\n    ├── .prettierrc.json          # Prettier formatting\n    ├── .stylelintrc              # Stylelint rules\n    ├── .browserslistrc           # Target browsers\n    └── .cursorrules              # AI context (Cursor IDE)\n```\n\n## Build Pipeline Details\n\n### Development Mode (`npm start`)\n\n1. **Clean**: Remove old compiled files\n2. **Compile Pug**: `src/pug/**/*.pug` → `src/views/*.html`\n3. **Compile Sass**: `src/scss/*.scss` → `dist/css/*.css` (expanded, autoprefixed)\n4. **Sync JS**: `src/js/*.js` → `dist/js/*.js` (copied as-is via `sync-directory`, no transform)\n5. **Copy Assets**: `src/assets/**/*` → `dist/assets/`\n6. **Build Vendors**: Bundle third-party libraries\n7. **Watch Files**: Monitor changes and recompile\n8. **Browser-sync**: Live reload server on http://localhost:3000\n\n### Production Build (`npm run build`)\n\n1. **All development steps**\n2. **Minify CSS**: Compress stylesheets with clean-css-cli\n3. **JS**: No separate minify step - shipped as synced source\n4. **Optimize Assets**: Copy optimized files\n5. **Generate zip**: Create distribution package\n\n### File Watching\n\n```\nnpm run watch          # Watch all file types\nnpm run watch-pug      # Watch Pug templates only\nnpm run watch-css      # Watch Sass files only\nnpm run watch-js       # Watch JavaScript files only\n```\n\nEach watch task uses **nodemon** to monitor file changes and trigger appropriate compilation.\n\n## Data Flow\n\n### Page Rendering Flow\n\n```\n1. Browser Request\n   └─> /index.html\n\n2. Server Response\n   └─> Serve dist/index.html (static file)\n\n3. HTML Loads Resources\n   ├─> dist/css/style.css (Bootstrap + CoreUI + custom styles)\n   ├─> dist/js/main.js (app initialization)\n   └─> dist/vendors/*.js (Chart.js, SimpleBar, etc.)\n\n4. JavaScript Execution\n   ├─> Initialize CoreUI components\n   ├─> Set up event listeners\n   ├─> Configure charts (if on dashboard)\n   └─> Enable tooltips/popovers\n\n5. User Interaction\n   └─> JavaScript handles UI updates (no page reload)\n```\n\n### Theme Switching Flow\n\n```\n1. User clicks theme toggle button\n   └─> color-modes.js listens for click\n\n2. ColorModeStorageManager updates preference\n   ├─> Save to localStorage\n   └─> Update [data-coreui-theme] attribute\n\n3. CSS custom properties respond\n   └─> Variables change (--cui-primary-bg, --cui-text-color, etc.)\n\n4. ColorSchemeChange event fires\n   └─> Charts re-render with new theme colors\n```\n\n### Chart Rendering Flow\n\n```\n1. charts.js module loads\n   └─> import Chart from 'chart.js/auto'\n\n2. DOM ready\n   └─> Find chart canvas elements\n\n3. Fetch data (or use inline data)\n   └─> Random data generator for demo\n\n4. Create Chart.js instance\n   ├─> Configure chart type (line, bar, pie, etc.)\n   ├─> Apply theme colors from CSS variables\n   └─> Set responsive options\n\n5. Theme changes\n   └─> Re-initialize charts with new colors\n```\n\n## Component Organization\n\n### Pug Template Hierarchy\n\n```\ndefault.pug (main layout — dashboard/component pages)\n├─> sidebar.pug (side navigation)\n│   └─> sidebar-nav.pug (data-driven nav items)\n├─> header.pug (top navigation bar)\n│   └─> block breadcrumb\n├─> block canonical / block styles\n├─> block view\n│   └─> index.pug / components/*.pug / etc. (page content)\n└─> footer.pug (page footer)\n    └─> scripts.pug (common script includes)\n        └─> block scripts / block js\n\npages.pug (standalone layout — auth & error pages)\n├─> block styles\n└─> block view\n    └─> authentication/*.pug / error-pages/*.pug\n```\n\n**Block System:**\n- `block view`: Main page content area (both layouts)\n- `block canonical`: `<link rel=\"canonical\">` override (`default.pug` only)\n- `block breadcrumb`: Breadcrumb trail, declared inside `header.pug` (`default.pug` only)\n- `block scripts` / `block js`: Page-specific script includes, declared inside `scripts.pug`\n- Each view extends a layout and overrides only the blocks it needs\n\n### CSS Architecture\n\n```\nstyle.scss\n├─> Import Bootstrap 5\n├─> Import CoreUI components\n├─> Import custom variables\n└─> Import custom component styles\n\nTheme System:\n[data-coreui-theme=\"light\"]  # Light mode (default)\n[data-coreui-theme=\"dark\"]   # Dark mode\n[data-coreui-theme=\"auto\"]   # System preference\n```\n\n**CSS Custom Properties:**\n- `--cui-primary`, `--cui-secondary`, etc. (colors)\n- `--cui-bg`, `--cui-text-color` (backgrounds/text)\n- `--cui-border-color`, `--cui-shadow` (UI elements)\n\n### JavaScript Module Pattern\n\nEach JS file in `src/js/` is an ES6 module:\n\n```javascript\n// Import dependencies\nimport { Something } from '@coreui/coreui'\n\n// Define functionality\nconst doSomething = () => { /* ... */ }\n\n// Initialize on DOM ready\ndocument.addEventListener('DOMContentLoaded', () => {\n  doSomething()\n})\n\n// Export if needed (most files use side effects only)\n```\n\n## Key Dependencies\n\n### Runtime Dependencies\n\n| Package | Purpose | Used In |\n|---------|---------|---------|\n| `@coreui/coreui` | UI component library | All pages |\n| `@coreui/icons` | Icon library | Icon pages |\n| `chart.js` | Charts and graphs | Dashboard |\n| `simplebar` | Custom scrollbars | Sidebar |\n| `@coreui/utils` | Utility functions | Theme switching |\n\n### Build Dependencies\n\n| Package | Purpose |\n|---------|---------|\n| `sass` | CSS preprocessing |\n| `sync-directory` | Copy `src/js`, `src/assets`, `src/views` into `dist/` |\n| `pug` | HTML templating |\n| `postcss` | CSS post-processing |\n| `autoprefixer` | Vendor prefix automation |\n| `browser-sync` | Development server |\n| `eslint` | JavaScript linting |\n| `stylelint` | CSS linting |\n\n## Browser Support\n\nDefined in `.browserslistrc`:\n\n```\n>= 0.5%\nlast 2 major versions\nnot dead\nChrome >= 60\nFirefox >= 60\nFirefox ESR\niOS >= 12\nSafari >= 12\nnot Explorer <= 11\n```\n\nModern browsers with native ES2015+ support - this is also why `src/js` ships untranspiled (see [Build Tools](#build-tools)).\n\n## Deployment\n\n### Static Hosting (Recommended)\n\n1. Run `npm run build`\n2. Deploy `dist/` folder to:\n   - Netlify\n   - Vercel\n   - GitHub Pages\n   - AWS S3 + CloudFront\n   - Any static file server\n\n### Traditional Web Server\n\n1. Run `npm run build`\n2. Copy `dist/` contents to web root\n3. Configure server to serve `index.html` as default\n4. Set proper MIME types for CSS/JS files\n\n### Docker (Optional)\n\n```dockerfile\nFROM nginx:alpine\nCOPY dist/ /usr/share/nginx/html/\nEXPOSE 80\n```\n\n## Performance Considerations\n\n### CSS Optimization\n- Sass compilation removes unused styles\n- PostCSS autoprefixer adds only necessary prefixes\n- Minification in production build\n- CSS is render-blocking (loaded in `<head>`)\n\n### JavaScript Optimization\n- No transpilation or minification step - files are copied as-is (see [Build Tools](#build-tools))\n- Files loaded as separate scripts (no bundler)\n- Deferred script loading where possible\n\n### Asset Optimization\n- SVG icons (scalable, small file size)\n- Favicon in multiple formats for compatibility\n- Images in `src/assets/` should be optimized before adding\n\n## Security Considerations\n\n### Content Security Policy (CSP)\nTemplate includes inline scripts and styles. For strict CSP:\n1. Extract inline scripts to external files\n2. Use nonces or hashes for required inline scripts\n3. Update CSP headers accordingly\n\n### XSS Prevention\n- Pug automatically escapes HTML by default\n- Use `!= html` only for trusted content\n- Sanitize user input on server-side (if adding backend)\n\n### Dependency Management\n- Regularly update npm dependencies\n- Run `npm audit` to check for vulnerabilities\n- Pin major versions in `package.json`\n\n## Extensibility\n\n### Adding New Pages\n\n1. Create `src/pug/views/my-page.pug`\n2. Extend layout: `extends ../_layout/default.pug`\n3. Override the `view` block (see [Block System](#pug-template-hierarchy)):\n   ```pug\n   block view\n     .container-lg.px-4\n       h1 My Page Title\n       p Page content here\n   ```\n4. Add an entry to `src/pug/_partials/sidebar-nav.pug` so the page is reachable from the sidebar\n5. Run `npm run pug` (or `npm start`) to compile\n6. Access at `/my-page.html`\n\n### Adding New Components\n\n1. Check CoreUI docs: https://coreui.io/bootstrap/docs/\n2. Copy component markup to Pug file\n3. Convert HTML to Pug syntax (use html2pug.com if needed)\n4. Import required JavaScript:\n   ```javascript\n   import { Modal } from '@coreui/coreui'\n   ```\n5. Initialize component in page-specific JS\n\n### Adding New Styles\n\n1. Edit `src/scss/style.scss` or create new partial\n2. Use Sass modules syntax to import CoreUI:\n   ```scss\n   @use \"@coreui/coreui/scss/coreui\" as * with (\n     $enable-deprecation-messages: false\n   );\n   ```\n   For CoreUI Pro projects:\n   ```scss\n   @use \"@coreui/coreui-pro/scss/coreui\" as * with (\n     $enable-deprecation-messages: false\n   );\n   ```\n3. Use CSS custom properties for theme compatibility\n4. Run `npm run css` to compile\n\n### Integrating Backend APIs\n\nThis template is frontend-only. To add backend:\n\n1. **Fetch API** for AJAX requests:\n   ```javascript\n   fetch('/api/endpoint')\n     .then(response => response.json())\n     .then(data => updateUI(data))\n   ```\n\n2. **Authentication**: Implement token-based auth\n   - Store JWT in localStorage/sessionStorage\n   - Add Authorization header to requests\n   - Redirect to login on 401 responses\n\n3. **State Management**: For complex apps, consider:\n   - Vanilla JS with custom events\n   - Lightweight state library (Zustand, Nano Stores)\n   - Full framework migration (React, Vue, etc.)\n\n## Common Issues and Solutions\n\n### Pug Compilation Errors\n- **Error**: \"Cannot find module\"\n  - **Fix**: Check Pug include/extend paths (relative to file)\n\n### Sass Compilation Errors\n- **Error**: \"Undefined variable\"\n  - **Fix**: Import Bootstrap/CoreUI variables before using\n\n### JavaScript Errors\n- **Error**: \"X is not defined\"\n  - **Fix**: Add `/* global X */` comment or import module\n\n### Live Reload Not Working\n- **Error**: Browser-sync not updating\n  - **Fix**: Check if `watch` scripts are running, restart `npm start`\n\n### Build Fails\n- **Error**: npm scripts fail\n  - **Fix**: Delete `node_modules/` and `dist/`, run `npm install`, then `npm run build`\n\n## Resources\n\n- **CoreUI Bootstrap Docs**: https://coreui.io/bootstrap/docs/\n- **Pug Documentation**: https://pugjs.org/\n- **Chart.js Documentation**: https://www.chartjs.org/\n- **Sass Documentation**: https://sass-lang.com/documentation/\n\n## Changelog\n\nSee [releases](https://github.com/coreui/coreui-free-bootstrap-admin-template/releases) for version history and updates.\n","isInternal":false,"tokens":4581,"sizeBytes":19466},{"name":".cursorrules","path":".cursorrules","rawUrl":"https://raw.githubusercontent.com/coreui/coreui-free-bootstrap-admin-template/HEAD/.cursorrules","title":"Cursor IDE Native Rules","category":"cursor-rule","format":"markdown","content":"# CoreUI Free Bootstrap Admin Template - AI Context\n\n## Project Overview\nThis is a Bootstrap 5 admin dashboard template built with CoreUI components. It uses Pug templating, Sass for styles, and vanilla JavaScript for interactivity.\n\n## Critical Rules\n\n### Component Library\n- **ALWAYS use CoreUI Bootstrap components**: https://coreui.io/bootstrap/docs/\n- **NEVER use Tailwind CSS** - this project uses Bootstrap 5 and custom Sass\n- Use CoreUI's CSS classes and JavaScript components from `@coreui/coreui` package\n- Reference the official CoreUI docs for component syntax and options\n\n### Technology Stack\n- **HTML Generation**: Pug templates (NOT raw HTML)\n- **Styling**: Sass/SCSS with Bootstrap 5 (NO Tailwind)\n- **JavaScript**: Vanilla JS with ES6 modules (NO frameworks like React/Vue)\n- **Build System**: npm scripts with Babel, PostCSS, and custom build scripts\n\n## Code Conventions\n\n### JavaScript\n- **No semicolons** - enforced by ESLint\n- **2-space indentation**\n- **ES6 modules** with import/export\n- **Strict mode** enabled\n- Use `/* global VariableName */` for external libraries\n- Follow XO ESLint config with Unicorn plugin rules\n\n### File Structure\n```\nsrc/\n├── js/          # JavaScript modules (keep small and focused)\n├── scss/        # Sass stylesheets (imports Bootstrap and CoreUI)\n├── pug/         # Pug templates (source of truth for HTML)\n│   ├── _layout/     # Base layouts\n│   ├── _partials/   # Reusable components\n│   ├── _mixins/     # Pug mixins\n│   └── views/       # Page templates\n├── assets/      # Images, icons, static files\n└── views/       # Compiled HTML (auto-generated, don't edit)\n```\n\n### Pug Templates\n- Use `extends ../_layout/default.pug` for new pages\n- Override blocks: `block content`, `block scripts`\n- Use mixins from `_mixins/` for common patterns\n- Follow existing naming conventions for consistency\n\n### CSS/Sass\n- Use Bootstrap utilities first before custom CSS\n- Use CSS custom properties (CSS variables) for theming\n- Use Bootstrap/CoreUI class naming conventions (e.g., `.sidebar`, `.header`, `.card-title`)\n- Support dark mode via `[data-coreui-theme=\"dark\"]`\n- **Never use**: `border-radius`, `transition`, `calc()` directly (Stylelint enforced)\n\n### Naming Conventions\n- **Files**: kebab-case (e.g., `color-modes.js`, `_header.pug`)\n- **CSS classes**: Bootstrap/CoreUI conventions (e.g., `.btn-primary`, `.card-header`)\n- **JavaScript variables**: camelCase\n- **Constants**: UPPER_SNAKE_CASE\n\n## Development Workflow\n\n### Adding New Pages\n1. Create Pug template in `src/pug/views/`\n2. Extend base layout: `extends ../_layout/default.pug`\n3. Add page-specific styles in `src/scss/` if needed\n4. Add page-specific JS in `src/js/` if needed\n5. Run `npm start` to compile and preview\n\n### Adding New Components\n1. **First check CoreUI docs**: https://coreui.io/bootstrap/docs/\n2. Use CoreUI component markup in Pug files\n3. Import required CoreUI JS modules if needed\n4. Style using CoreUI/Bootstrap classes, not custom CSS\n5. Create Pug mixin in `src/pug/_mixins/` for reusable patterns\n\n### Build Commands\n- `npm start` - Development with live reload\n- `npm run build` - Production build\n- `npm run watch-css` - Watch Sass changes\n- `npm run watch-js` - Watch JavaScript changes\n- `npm run watch-pug` - Watch Pug changes\n\n## Code Quality\n\n### Linting\n- **JavaScript**: ESLint with XO config (flat config format)\n- **Styles**: Stylelint with Bootstrap config\n- **Formatting**: Prettier for HTML output\n- Run `npm run lint` before committing\n\n### Comments and Documentation\n- **JSDoc required** for all functions with parameters\n- Explain \"why\", not \"what\"\n- Document complex template logic in Pug files\n- Add file-level comments explaining module purpose\n\n### Git Commits\nFollow semantic commit format:\n- `feat:` - New feature\n- `fix:` - Bug fix\n- `docs:` - Documentation changes\n- `style:` - Code style changes (formatting)\n- `refactor:` - Code refactoring\n- `test:` - Test additions/changes\n- `chore:` - Build/tooling changes\n\n## Common Patterns\n\n### Chart Integration\n```javascript\n/* global Chart */\nimport { getStyle } from '@coreui/utils'\n\nconst chart = new Chart(ctx, {\n  type: 'line',\n  data: { /* ... */ },\n  options: { /* ... */ }\n})\n```\n\n### Theme Switching\n```javascript\nimport { ColorModeStorageManager } from '@coreui/coreui/js/color-modes'\n\ndocument.addEventListener('ColorSchemeChange', () => {\n  // React to theme changes\n})\n```\n\n### Pug Mixin Usage\n```pug\ninclude _mixins/breadcrumb\n+breadcrumb(['Home', 'Components', 'Buttons'])\n```\n\n## AI Assistance Guidelines\n\n### When AI Should\n- Use CoreUI Bootstrap components from official docs\n- Generate Pug templates, not raw HTML\n- Follow existing patterns in the codebase\n- Add JSDoc comments to new JavaScript functions\n- Respect ESLint/Stylelint rules\n- Suggest npm scripts for tasks\n\n### When AI Should NOT\n- Use Tailwind CSS classes\n- Use React/Vue/Angular components\n- Edit compiled files in `dist/` or `src/views/`\n- Add unnecessary dependencies\n- Break existing build pipeline\n- Ignore linting errors\n\n## External Dependencies\n\n### Core Libraries\n- `@coreui/coreui` - CoreUI component library\n- `chart.js` - Charts and graphs\n- `simplebar` - Custom scrollbars\n\n### Build Tools\n- `sass` - CSS preprocessor\n- `@babel/core` - JavaScript transpiler\n- `pug` - HTML templating\n- `postcss` - CSS post-processing\n- `browser-sync` - Live reload server\n\n## Browser Support\nDefined in `.browserslistrc`:\n- Last 1 major version of modern browsers\n- Chrome, Firefox, Edge, Safari\n- iOS Safari, Chrome Android\n\n## Resources\n- CoreUI Docs: https://coreui.io/bootstrap/docs/\n- Chart.js Docs: https://www.chartjs.org/\n- Pug Docs: https://pugjs.org/\n\n## Project Maintainer Notes\n- License: MIT\n- Version: 5.5.0\n- Repository: https://github.com/coreui/coreui-free-bootstrap-admin-template\n","isInternal":false,"tokens":1480,"sizeBytes":5863}],"systemPromptSnippet":"<yakaai_skills repo=\"coreui/coreui-free-bootstrap-admin-template\">\n<!-- File: ARCHITECTURE.md (Tokens: ~4581 | Category: project-spec) -->\n# Architecture Documentation\n\n## Project Purpose\n\nCoreUI Free Bootstrap Admin Template is a professional admin dashboard template built on Bootstrap 5 and CoreUI components. It provides a ready-to-use foundation for building admin panels, dashboards, and web applications with a clean, modern interface.\n\n**Key Characteristics:**\n- Server-side templating approach (Pug → HTML)\n- Bootstrap 5 + CoreUI component library\n- Vanilla JavaScript (no framework dependencies)\n- Multi-page application (MPA) architecture\n- Static file generation with build-time compilation\n\n## High-Level Architecture\n\n```\n┌─────────────────────────────────────────────────────┐\n│                   Source Files                      │\n│  ┌──────────┐  ┌──────────┐  ┌──────────┐           │\n│  │   Pug    │  │   Sass   │  │    JS    │           │\n│  │Templates │  │  Styles  │  │ Modules  │           │\n│  └────┬─────┘  └────┬─────┘  └────┬─────┘           │\n│       │             │             │                 │\n└───────┼─────────────┼─────────────┼─────────────────┘\n        │             │             │\n        ▼             ▼             ▼\n┌─────────────────────────────────────────────────────┐\n│                  Build Pipeline                     │\n│  ┌──────────┐  ┌──────────┐  ┌──────────┐           │\n│  │   Pug    │  │PostCSS + │  │ syncdir  │           │\n│  │Compiler  │  │  Sass    │  │(copy JS) │           │\n│  └────┬─────┘  └────┬─────┘  └────┬─────┘           │\n│       │             │             │                 │\n└───────┼─────────────┼─────────────┼─────────────────┘\n        │             │             │\n        ▼             ▼             ▼\n┌─────────────────────────────────────────────────────┐\n│                 Distribution Files                  │\n│  ┌──────────┐  ┌──────────┐  ┌──────────┐           │\n│  │   HTML   │  │   CSS    │  │    JS    │           │\n│  │  Files   │  │ (minified)│  │(bundled) │          │\n│  └──────────┘  └──────────┘  └──────────┘           │\n│         (served via browser-sync or web server)     │\n└─────────────────────────────────────────────────────┘\n```\n\n## Technology Stack\n\n### Frontend\n- **HTML Generation**: Pug 3.0.3 (template engine)\n- **CSS Framework**: Bootstrap 5.3.x\n- **Component Library**: CoreUI 5.x (@coreui/coreui)\n- **Icons**: CoreUI Icons (@coreui/icons)\n- **JavaScript**: Vanilla ES6+ (no framework)\n- **Charts**: Chart.js 4.x\n- **Scrollbars**: SimpleBar 6.x\n\n### Build Tools\n- **Package Manager**: npm\n- **CSS Processing**: Sass 1.102.x → PostCSS → Autoprefixer\n- **JS**: plain ES2015+, copied as-is via `sync-directory` (no transpilation - the declared browser targets already support the syntax used, see [Browser Support](#browser-support))\n- **Task Runner**: npm scripts with npm-run-all\n- **File Watching**: Nodemon\n- **Live Server**: Browser-sync 3.0.4\n\n### Code Quality\n- **Linting**: ESLint 9.x (flat config) with XO + Unicorn\n- **Style Linting**: Stylelint 16.x with Bootstrap config\n- **Formatting**: Prettier 3.9.x\n- **Editor Config**: .editorconfig for consistency\n\n## Directory Structure\n\n```\ncoreui-free-bootstrap-admin-template/\n│\n├── src/                          # Source files (edit these)\n│   ├── pug/                      # Pug templates (HTML source)\n│   │   ├── _layout/              # Base layout templates\n│   │   │   ├── default.pug       # Main layout with sidebar/header\n│   │   │   └── pages.pug         # Standalone pages layout (auth, errors)\n│   │   ├── _partials/            # Reusable components\n│   │   │   ├── banner.pug        # Top announcement banner\n│   │   │   ├── head.pug          # HTML <head> section\n│   │   │   ├── header.pug        # Top navigation bar\n│   │   │   ├── sidebar.pug       # Left sidebar wrapper\n│   │   │   ├── sidebar-nav.pug   # Sidebar navigation items (data-driven)\n│   │   │   ├── footer.pug        # Page footer\n│   │   │   ├── scripts.pug       # Common script includes\n│   │   │   └── docs-icons.pug    # Icon documentation helpers\n│   │   ├── _mixins/              # Pug helper mixins\n│   │   │   ├── breadcrumb.pug    # Breadcrumb generator\n│   │   │   ├── callout.pug       # Alert/callout boxes\n│   │   │   ├── callout-custom.pug # Custom callout variant\n│   │   │   ├── docs-components.pug # Docs component helpers\n│   │   │   ├── example.pug       # Code example displays\n│   │   │   └── inline-svg.pug    # Inline SVG helper\n│   │   └── views/                # Page templates\n│   │       ├── index.pug         # Main dashboard page\n│   │       ├── blank.pug         # Blank page template\n│   │       ├── charts.pug        # Charts page\n│   │       ├── widgets.pug       # Widgets page\n│   │       ├── authentication/   # Auth pages (login, register, etc.)\n│   │       ├── components/       # UI components (buttons, modals, etc.)\n│   │       ├── error-pages/      # Error pages (404, 500)\n│   │       ├── forms/            # Form components\n│   │       └── icons/            # Icon libraries\n│   │\n│   ├── scss/                     # Sass stylesheets\n│   │   ├── style.scss            # Main stylesheet entry\n│   │   ├── style-rtl.scss        # RTL (right-to-left) styles\n│   │   └── examples.scss         # Demo/example page styles\n│   │\n│   ├── js/                       # JavaScript modules\n│   │   ├── main.js               # Main entry point\n│   │   ├── charts.js             # Chart.js configurations\n│   │   ├── color-modes.js        # Dark/light theme switcher\n│   │   ├── config.js             # App configuration / shared settings\n│   │   ├── tooltips.js           # Tooltip initialization\n│   │   ├── popovers.js           # Popover initialization\n│   │   ├── toasts.js             # Toast notification initialization\n│   │   └── widgets.js            # Widgets page charts\n│   │\n│   ├── assets/                   # Static assets\n│   │   ├── brand/                # Logo files\n│   │   ├── favicon/              # Favicon files\n│   │   └── img/                  # Images\n│   │\n│   └── views/                    # Compiled HTML (auto-generated)\n│       └── *.html                # Do NOT edit these manually\n│\n├── dist/                         # Production build output\n│   ├── css/                      # Minified CSS\n│   ├── js/                       # Synced JS (copied as-is, no transform)\n│   ├── assets/                   # Copied assets\n│   ├── vendors/                  # Third-party libraries\n│   └── *.html                    # Production HTML files\n│\n├── build/                        # Build scripts\n│   ├── pug.mjs                   # Pug compilation script\n│   ├── postcss.config.mjs        # PostCSS configuration\n│   ├── vendors.mjs               # Vendor file bundling\n│   └── format-html.mjs           # HTML formatting/prettifying\n│\n├── node_modules/                 # npm dependencies (ignored)\n│\n└── Configuration files\n    ├── package.json              # Dependencies and scripts\n    ├── .editorconfig             # Editor settings\n    ├── eslint.config.mjs         # ESLint flat config\n    ├── .prettierrc.json          # Prettier formatting\n    ├── .stylelintrc              # Stylelint rules\n    ├── .browserslistrc           # Target browsers\n    └── .cursorrules              # AI context (Cursor IDE)\n```\n\n## Build Pipeline Details\n\n### Development Mode (`npm start`)\n\n1. **Clean**: Remove old compiled files\n2. **Compile Pug**: `src/pug/**/*.pug` → `src/views/*.html`\n3. **Compile Sass**: `src/scss/*.scss` → `dist/css/*.css` (expanded, autoprefixed)\n4. **Sync JS**: `src/js/*.js` → `dist/js/*.js` (copied as-is via `sync-directory`, no transform)\n5. **Copy Assets**: `src/assets/**/*` → `dist/assets/`\n6. **Build Vendors**: Bundle third-party libraries\n7. **Watch Files**: Monitor changes and recompile\n8. **Browser-sync**: Live reload server on http://localhost:3000\n\n### Production Build (`npm run build`)\n\n1. **All development steps**\n2. **Minify CSS**: Compress stylesheets with clean-css-cli\n3. **JS**: No separate minify step - shipped as synced source\n4. **Optimize Assets**: Copy optimized files\n5. **Generate zip**: Create distribution package\n\n### File Watching\n\n```\nnpm run watch          # Watch all file types\nnpm run watch-pug      # Watch Pug templates only\nnpm run watch-css      # Watch Sass files only\nnpm run watch-js       # Watch JavaScript files only\n```\n\nEach watch task uses **nodemon** to monitor file changes and trigger appropriate compilation.\n\n## Data Flow\n\n### Page Rendering Flow\n\n```\n1. Browser Request\n   └─> /index.html\n\n2. Server Response\n   └─> Serve dist/index.html (static file)\n\n3. HTML Loads Resources\n   ├─> dist/css/style.css (Bootstrap + CoreUI + custom styles)\n   ├─> dist/js/main.js (app initialization)\n   └─> dist/vendors/*.js (Chart.js, SimpleBar, etc.)\n\n4. JavaScript Execution\n   ├─> Initialize CoreUI components\n   ├─> Set up event listeners\n   ├─> Configure charts (if on dashboard)\n   └─> Enable tooltips/popovers\n\n5. User Interaction\n   └─> JavaScript handles UI updates (no page reload)\n```\n\n### Theme Switching Flow\n\n```\n1. User clicks theme toggle button\n   └─> color-modes.js listens for click\n\n2. ColorModeStorageManager updates preference\n   ├─> Save to localStorage\n   └─> Update [data-coreui-theme] attribute\n\n3. CSS custom properties respond\n   └─> Variables change (--cui-primary-bg, --cui-text-color, etc.)\n\n4. ColorSchemeChange event fires\n   └─> Charts re-render with new theme colors\n```\n\n### Chart Rendering Flow\n\n```\n1. charts.js module loads\n   └─> import Chart from 'chart.js/auto'\n\n2. DOM ready\n   └─> Find chart canvas elements\n\n3. Fetch data (or use inline data)\n   └─> Random data generator for demo\n\n4. Create Chart.js instance\n   ├─> Configure chart type (line, bar, pie, etc.)\n   ├─> Apply theme colors from CSS variables\n   └─> Set responsive options\n\n5. Theme changes\n   └─> Re-initialize charts with new colors\n```\n\n## Component Organization\n\n### Pug Template Hierarchy\n\n```\ndefault.pug (main layout — dashboard/component pages)\n├─> sidebar.pug (side navigation)\n│   └─> sidebar-nav.pug (data-driven nav items)\n├─> header.pug (top navigation bar)\n│   └─> block breadcrumb\n├─> block canonical / block styles\n├─> block view\n│   └─> index.pug / components/*.pug / etc. (page content)\n└─> footer.pug (page footer)\n    └─> scripts.pug (common script includes)\n        └─> block scripts / block js\n\npages.pug (standalone layout — auth & error pages)\n├─> block styles\n└─> block view\n    └─> authentication/*.pug / error-pages/*.pug\n```\n\n**Block System:**\n- `block view`: Main page content area (both layouts)\n- `block canonical`: `<link rel=\"canonical\">` override (`default.pug` only)\n- `block breadcrumb`: Breadcrumb trail, declared inside `header.pug` (`default.pug` only)\n- `block scripts` / `block js`: Page-specific script includes, declared inside `scripts.pug`\n- Each view extends a layout and overrides only the blocks it needs\n\n### CSS Architecture\n\n```\nstyle.scss\n├─> Import Bootstrap 5\n├─> Import CoreUI components\n├─> Import custom variables\n└─> Import custom component styles\n\nTheme System:\n[data-coreui-theme=\"light\"]  # Light mode (default)\n[data-coreui-theme=\"dark\"]   # Dark mode\n[data-coreui-theme=\"auto\"]   # System preference\n```\n\n**CSS Custom Properties:**\n- `--cui-primary`, `--cui-secondary`, etc. (colors)\n- `--cui-bg`, `--cui-text-color` (backgrounds/text)\n- `--cui-border-color`, `--cui-shadow` (UI elements)\n\n### JavaScript Module Pattern\n\nEach JS file in `src/js/` is an ES6 module:\n\n```javascript\n// Import dependencies\nimport { Something } from '@coreui/coreui'\n\n// Define functionality\nconst doSomething = () => { /* ... */ }\n\n// Initialize on DOM ready\ndocument.addEventListener('DOMContentLoaded', () => {\n  doSomething()\n})\n\n// Export if needed (most files use side effects only)\n```\n\n## Key Dependencies\n\n### Runtime Dependencies\n\n| Package | Purpose | Used In |\n|---------|---------|---------|\n| `@coreui/coreui` | UI component library | All pages |\n| `@coreui/icons` | Icon library | Icon pages |\n| `chart.js` | Charts and graphs | Dashboard |\n| `simplebar` | Custom scrollbars | Sidebar |\n| `@coreui/utils` | Utility functions | Theme switching |\n\n### Build Dependencies\n\n| Package | Purpose |\n|---------|---------|\n| `sass` | CSS preprocessing |\n| `sync-directory` | Copy `src/js`, `src/assets`, `src/views` into `dist/` |\n| `pug` | HTML templating |\n| `postcss` | CSS post-processing |\n| `autoprefixer` | Vendor prefix automation |\n| `browser-sync` | Development server |\n| `eslint` | JavaScript linting |\n| `stylelint` | CSS linting |\n\n## Browser Support\n\nDefined in `.browserslistrc`:\n\n```\n>= 0.5%\nlast 2 major versions\nnot dead\nChrome >= 60\nFirefox >= 60\nFirefox ESR\niOS >= 12\nSafari >= 12\nnot Explorer <= 11\n```\n\nModern browsers with native ES2015+ support - this is also why `src/js` ships untranspiled (see [Build Tools](#build-tools)).\n\n## Deployment\n\n### Static Hosting (Recommended)\n\n1. Run `npm run build`\n2. Deploy `dist/` folder to:\n   - Netlify\n   - Vercel\n   - GitHub Pages\n   - AWS S3 + CloudFront\n   - Any static file server\n\n### Traditional Web Server\n\n1. Run `npm run build`\n2. Copy `dist/` contents to web root\n3. Configure server to serve `index.html` as default\n4. Set proper MIME types for CSS/JS files\n\n### Docker (Optional)\n\n```dockerfile\nFROM nginx:alpine\nCOPY dist/ /usr/share/nginx/html/\nEXPOSE 80\n```\n\n## Performance Considerations\n\n### CSS Optimization\n- Sass compilation removes unused styles\n- PostCSS autoprefixer adds only necessary prefixes\n- Minification in production build\n- CSS is render-blocking (loaded in `<head>`)\n\n### JavaScript Optimization\n- No transpilation or minification step - files are copied as-is (see [Build Tools](#build-tools))\n- Files loaded as separate scripts (no bundler)\n- Deferred script loading where possible\n\n### Asset Optimization\n- SVG icons (scalable, small file size)\n- Favicon in multiple formats for compatibility\n- Images in `src/assets/` should be optimized before adding\n\n## Security Considerations\n\n### Content Security Policy (CSP)\nTemplate includes inline scripts and styles. For strict CSP:\n1. Extract inline scripts to external files\n2. Use nonces or hashes for required inline scripts\n3. Update CSP headers accordingly\n\n### XSS Prevention\n- Pug automatically escapes HTML by default\n- Use `!= html` only for trusted content\n- Sanitize user input on server-side (if adding backend)\n\n### Dependency Management\n- Regularly update npm dependencies\n- Run `npm audit` to check for vulnerabilities\n- Pin major versions in `package.json`\n\n## Extensibility\n\n### Adding New Pages\n\n1. Create `src/pug/views/my-page.pug`\n2. Extend layout: `extends ../_layout/default.pug`\n3. Override the `view` block (see [Block System](#pug-template-hierarchy)):\n   ```pug\n   block view\n     .container-lg.px-4\n       h1 My Page Title\n       p Page content here\n   ```\n4. Add an entry to `src/pug/_partials/sidebar-nav.pug` so the page is reachable from the sidebar\n5. Run `npm run pug` (or `npm start`) to compile\n6. Access at `/my-page.html`\n\n### Adding New Components\n\n1. Check CoreUI docs: https://coreui.io/bootstrap/docs/\n2. Copy component markup to Pug file\n3. Convert HTML to Pug syntax (use html2pug.com if needed)\n4. Import required JavaScript:\n   ```javascript\n   import { Modal } from '@coreui/coreui'\n   ```\n5. Initialize component in page-specific JS\n\n### Adding New Styles\n\n1. Edit `src/scss/style.scss` or create new partial\n2. Use Sass modules syntax to import CoreUI:\n   ```scss\n   @use \"@coreui/coreui/scss/coreui\" as * with (\n     $enable-deprecation-messages: false\n   );\n   ```\n   For CoreUI Pro projects:\n   ```scss\n   @use \"@coreui/coreui-pro/scss/coreui\" as * with (\n     $enable-deprecation-messages: false\n   );\n   ```\n3. Use CSS custom properties for theme compatibility\n4. Run `npm run css` to compile\n\n### Integrating Backend APIs\n\nThis template is frontend-only. To add backend:\n\n1. **Fetch API** for AJAX requests:\n   ```javascript\n   fetch('/api/endpoint')\n     .then(response => response.json())\n     .then(data => updateUI(data))\n   ```\n\n2. **Authentication**: Implement token-based auth\n   - Store JWT in localStorage/sessionStorage\n   - Add Authorization header to requests\n   - Redirect to login on 401 responses\n\n3. **State Management**: For complex apps, consider:\n   - Vanilla JS with custom events\n   - Lightweight state library (Zustand, Nano Stores)\n   - Full framework migration (React, Vue, etc.)\n\n## Common Issues and Solutions\n\n### Pug Compilation Errors\n- **Error**: \"Cannot find module\"\n  - **Fix**: Check Pug include/extend paths (relative to file)\n\n### Sass Compilation Errors\n- **Error**: \"Undefined variable\"\n  - **Fix**: Import Bootstrap/CoreUI variables before using\n\n### JavaScript Errors\n- **Error**: \"X is not defined\"\n  - **Fix**: Add `/* global X */` comment or import module\n\n### Live Reload Not Working\n- **Error**: Browser-sync not updating\n  - **Fix**: Check if `watch` scripts are running, restart `npm start`\n\n### Build Fails\n- **Error**: npm scripts fail\n  - **Fix**: Delete `node_modules/` and `dist/`, run `npm install`, then `npm run build`\n\n## Resources\n\n- **CoreUI Bootstrap Docs**: https://coreui.io/bootstrap/docs/\n- **Pug Documentation**: https://pugjs.org/\n- **Chart.js Documentation**: https://www.chartjs.org/\n- **Sass Documentation**: https://sass-lang.com/documentation/\n\n## Changelog\n\nSee [releases](https://github.com/coreui/coreui-free-bootstrap-admin-template/releases) for version history and updates.\n\n<!-- File: .cursorrules (Tokens: ~1480 | Category: cursor-rule) -->\n# CoreUI Free Bootstrap Admin Template - AI Context\n\n## Project Overview\nThis is a Bootstrap 5 admin dashboard template built with CoreUI components. It uses Pug templating, Sass for styles, and vanilla JavaScript for interactivity.\n\n## Critical Rules\n\n### Component Library\n- **ALWAYS use CoreUI Bootstrap components**: https://coreui.io/bootstrap/docs/\n- **NEVER use Tailwind CSS** - this project uses Bootstrap 5 and custom Sass\n- Use CoreUI's CSS classes and JavaScript components from `@coreui/coreui` package\n- Reference the official CoreUI docs for component syntax and options\n\n### Technology Stack\n- **HTML Generation**: Pug templates (NOT raw HTML)\n- **Styling**: Sass/SCSS with Bootstrap 5 (NO Tailwind)\n- **JavaScript**: Vanilla JS with ES6 modules (NO frameworks like React/Vue)\n- **Build System**: npm scripts with Babel, PostCSS, and custom build scripts\n\n## Code Conventions\n\n### JavaScript\n- **No semicolons** - enforced by ESLint\n- **2-space indentation**\n- **ES6 modules** with import/export\n- **Strict mode** enabled\n- Use `/* global VariableName */` for external libraries\n- Follow XO ESLint config with Unicorn plugin rules\n\n### File Structure\n```\nsrc/\n├── js/          # JavaScript modules (keep small and focused)\n├── scss/        # Sass stylesheets (imports Bootstrap and CoreUI)\n├── pug/         # Pug templates (source of truth for HTML)\n│   ├── _layout/     # Base layouts\n│   ├── _partials/   # Reusable components\n│   ├── _mixins/     # Pug mixins\n│   └── views/       # Page templates\n├── assets/      # Images, icons, static files\n└── views/       # Compiled HTML (auto-generated, don't edit)\n```\n\n### Pug Templates\n- Use `extends ../_layout/default.pug` for new pages\n- Override blocks: `block content`, `block scripts`\n- Use mixins from `_mixins/` for common patterns\n- Follow existing naming conventions for consistency\n\n### CSS/Sass\n- Use Bootstrap utilities first before custom CSS\n- Use CSS custom properties (CSS variables) for theming\n- Use Bootstrap/CoreUI class naming conventions (e.g., `.sidebar`, `.header`, `.card-title`)\n- Support dark mode via `[data-coreui-theme=\"dark\"]`\n- **Never use**: `border-radius`, `transition`, `calc()` directly (Stylelint enforced)\n\n### Naming Conventions\n- **Files**: kebab-case (e.g., `color-modes.js`, `_header.pug`)\n- **CSS classes**: Bootstrap/CoreUI conventions (e.g., `.btn-primary`, `.card-header`)\n- **JavaScript variables**: camelCase\n- **Constants**: UPPER_SNAKE_CASE\n\n## Development Workflow\n\n### Adding New Pages\n1. Create Pug template in `src/pug/views/`\n2. Extend base layout: `extends ../_layout/default.pug`\n3. Add page-specific styles in `src/scss/` if needed\n4. Add page-specific JS in `src/js/` if needed\n5. Run `npm start` to compile and preview\n\n### Adding New Components\n1. **First check CoreUI docs**: https://coreui.io/bootstrap/docs/\n2. Use CoreUI component markup in Pug files\n3. Import required CoreUI JS modules if needed\n4. Style using CoreUI/Bootstrap classes, not custom CSS\n5. Create Pug mixin in `src/pug/_mixins/` for reusable patterns\n\n### Build Commands\n- `npm start` - Development with live reload\n- `npm run build` - Production build\n- `npm run watch-css` - Watch Sass changes\n- `npm run watch-js` - Watch JavaScript changes\n- `npm run watch-pug` - Watch Pug changes\n\n## Code Quality\n\n### Linting\n- **JavaScript**: ESLint with XO config (flat config format)\n- **Styles**: Stylelint with Bootstrap config\n- **Formatting**: Prettier for HTML output\n- Run `npm run lint` before committing\n\n### Comments and Documentation\n- **JSDoc required** for all functions with parameters\n- Explain \"why\", not \"what\"\n- Document complex template logic in Pug files\n- Add file-level comments explaining module purpose\n\n### Git Commits\nFollow semantic commit format:\n- `feat:` - New feature\n- `fix:` - Bug fix\n- `docs:` - Documentation changes\n- `style:` - Code style changes (formatting)\n- `refactor:` - Code refactoring\n- `test:` - Test additions/changes\n- `chore:` - Build/tooling changes\n\n## Common Patterns\n\n### Chart Integration\n```javascript\n/* global Chart */\nimport { getStyle } from '@coreui/utils'\n\nconst chart = new Chart(ctx, {\n  type: 'line',\n  data: { /* ... */ },\n  options: { /* ... */ }\n})\n```\n\n### Theme Switching\n```javascript\nimport { ColorModeStorageManager } from '@coreui/coreui/js/color-modes'\n\ndocument.addEventListener('ColorSchemeChange', () => {\n  // React to theme changes\n})\n```\n\n### Pug Mixin Usage\n```pug\ninclude _mixins/breadcrumb\n+breadcrumb(['Home', 'Components', 'Buttons'])\n```\n\n## AI Assistance Guidelines\n\n### When AI Should\n- Use CoreUI Bootstrap components from official docs\n- Generate Pug templates, not raw HTML\n- Follow existing patterns in the codebase\n- Add JSDoc comments to new JavaScript functions\n- Respect ESLint/Stylelint rules\n- Suggest npm scripts for tasks\n\n### When AI Should NOT\n- Use Tailwind CSS classes\n- Use React/Vue/Angular components\n- Edit compiled files in `dist/` or `src/views/`\n- Add unnecessary dependencies\n- Break existing build pipeline\n- Ignore linting errors\n\n## External Dependencies\n\n### Core Libraries\n- `@coreui/coreui` - CoreUI component library\n- `chart.js` - Charts and graphs\n- `simplebar` - Custom scrollbars\n\n### Build Tools\n- `sass` - CSS preprocessor\n- `@babel/core` - JavaScript transpiler\n- `pug` - HTML templating\n- `postcss` - CSS post-processing\n- `browser-sync` - Live reload server\n\n## Browser Support\nDefined in `.browserslistrc`:\n- Last 1 major version of modern browsers\n- Chrome, Firefox, Edge, Safari\n- iOS Safari, Chrome Android\n\n## Resources\n- CoreUI Docs: https://coreui.io/bootstrap/docs/\n- Chart.js Docs: https://www.chartjs.org/\n- Pug Docs: https://pugjs.org/\n\n## Project Maintainer Notes\n- License: MIT\n- Version: 5.5.0\n- Repository: https://github.com/coreui/coreui-free-bootstrap-admin-template\n</yakaai_skills>"}