@appsbd/vue3-appsbd-ui 1.0.3 → 1.0.5

package/package.json

@@ -1,66 +1,72 @@
-{
-  "name": "@appsbd/vue3-appsbd-ui",
-  "version": "1.0.3",
-  "description": "Reusable Vue 3 component library",
-  "type": "module",
-  "main": "./dist/vue3-appsbd-ui.cjs.js",
-  "module": "./dist/vue3-appsbd-ui.es.js",
-  "style": "./dist/style.css",
-  "publishConfig": {
-    "access": "public"
-  },
-  "exports": {
-    ".": {
-      "import": "./dist/vue3-appsbd-ui.es.js",
-      "require": "./dist/vue3-appsbd-ui.cjs.js"
-    },
-    "./style.css": "./dist/style.css",
-    "./skins/*.css": "./dist/skins/*.css",
-    "./skins/*.scss": "./dist/skins/*.scss",
-    "./skins/themes/*.scss": "./dist/skins/themes/*.scss"
-  },
-  "files": [
-    "dist",
-    "readme.md",
-    "AI_REFERENCE.md",
-    ".ai",
-    "design-system.md"
-  ],
-  "scripts": {
-    "up": "npm run build && npm publish",
-    "dev": "vite --mode playground",
-    "lib": "vite",
-    "build": "vite build",
-    "build:playground": "vite build --mode playground",
-    "build:skins": "vite build --mode skins"
-  },
-  "keywords": [
-    "vue",
-    "vue3",
-    "component-library",
-    "vite"
-  ],
-  "author": "appsbd",
-  "license": "MIT",
-  "peerDependencies": {
-    "@appsbd/vue3-elite-grid": ">=2.0.4",
-    "@vee-validate/rules": ">=4.15.1",
-    "bootstrap": ">=5.3.7",
-    "lucide-vue-next": ">=0.575.0",
-    "vee-validate": ">=4.15.1",
-    "vue": ">=3.3.0",
-    "vue-router": ">=4.5.0",
-    "vue3-gettext": ">=2.4.0",
-    "tiny-emitter": ">=2.1.0",
-    "echarts": "^5.5.0",
-    "vue-echarts": "^6.6.9"
-  },
-  "devDependencies": {
-    "@vitejs/plugin-vue": "^5.0.0",
-    "bootstrap": "^5.3.0",
-    "sass-embedded": "^1.97.3",
-    "vite": "^5.0.0",
-    "highlight.js": "^11.11.1"
-  },
-  "dependencies": {}
-}
+{
+  "name": "@appsbd/vue3-appsbd-ui",
+  "version": "1.0.5",
+  "description": "Reusable Vue 3 component library",
+  "type": "module",
+  "main": "./dist/vue3-appsbd-ui.cjs.js",
+  "module": "./dist/vue3-appsbd-ui.es.js",
+  "style": "./dist/style.css",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/vue3-appsbd-ui.es.js",
+      "require": "./dist/vue3-appsbd-ui.cjs.js"
+    },
+    "./style.css": "./dist/style.css",
+    "./skins/*.css": "./dist/skins/*.css",
+    "./skins/*.scss": "./dist/skins/*.scss",
+    "./skins/themes/*.scss": "./dist/skins/themes/*.scss"
+  },
+  "files": [
+    "dist",
+    "readme.md",
+    "AI_REFERENCE.md",
+    "AI_REF.md",
+    ".ai",
+    "skills",
+    "scripts/postinstall.js",
+    "scripts/setup.js",
+    "scripts/skill-groups.js",
+    "design-system.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "up": "npm run build && npm publish",
+    "dev": "vite --mode playground",
+    "lib": "vite",
+    "build": "vite build",
+    "build:playground": "vite build --mode playground",
+    "build:skins": "vite build --mode skins"
+  },
+  "keywords": [
+    "vue",
+    "vue3",
+    "component-library",
+    "vite"
+  ],
+  "author": "appsbd",
+  "license": "MIT",
+  "peerDependencies": {
+    "@appsbd/vue3-elite-grid": ">=2.0.4",
+    "@vee-validate/rules": ">=4.15.1",
+    "bootstrap": ">=5.3.7",
+    "lucide-vue-next": ">=0.575.0",
+    "vee-validate": ">=4.15.1",
+    "vue": ">=3.3.0",
+    "vue-router": ">=4.5.0",
+    "vue3-gettext": ">=2.4.0",
+    "tiny-emitter": ">=2.1.0",
+    "echarts": ">=5.5.0",
+    "vue-echarts": ">=6.6.9"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^5.0.0",
+    "bootstrap": "^5.3.0",
+    "sass-embedded": "^1.97.3",
+    "vite": "^5.0.0",
+    "highlight.js": "^11.11.1"
+  },
+  "dependencies": {}
+}

package/readme.md

@@ -1,136 +1,194 @@
-# Vue 3 Appsbd UI Library
-
-A premium, reusable Vue 3 component library built for high-performance enterprise applications. Leverages **Vite**, **SCSS**, and **Bootstrap 5** to provide a rich set of UI components with built-in Dark Mode and RTL support.
-
-## 🚀 Key Features
-
-- **Vue 3 Composition API**: Optimized for performance and flexibility.
-- **Dynamic Theming**: Full dark mode support using Bootstrap's `data-bs-theme`.
-- **RTL Ready**: Built with CSS logical properties for global accessibility.
-- **Plugin System**: custom-built global systems for Toasts and Alerts.
-- **Enterprise Ready**: Includes complex components like MultiSelect, DatePicker, Wizard, Pricing Tables, and Filter Panels.
-- **Themable Skins**: 10 prebuilt color skins (default, green, red, cyan, purple, violet, pink, orange, gray, black) shipped as standalone CSS under `dist/skins/`.
-
-## 📦 Installation
-
-```bash
-npm install @appsbd/vue3-appsbd-ui
-```
-
-### Peer Dependencies
-
-Ensure you have the following installed in your project:
-
-```bash
-npm install bootstrap bootstrap-icons vee-validate @vee-validate/rules vue-router vue3-gettext lucide-vue-next tiny-emitter @appsbd/vue3-elite-grid
-```
-
-## 🤖 AI Assistant Integration
-
-If you are generating code in a project that consumes this library, provide your AI with the `AI_REFERENCE.md` file for immediate context on component existence, prop signatures, and usage patterns.
-
-## 🛠️ Setup
-
-Register the library and its styles in your main entry file (e.g., `main.js`):
-
-```javascript
-import { createApp } from "vue";
-import AppsbdUI from "@appsbd/vue3-appsbd-ui";
-import "@appsbd/vue3-appsbd-ui/style.css";
-
-const app = createApp(App);
-app.use(AppsbdUI);
-app.mount("#app");
-```
-
-### Applying a Theme Skin (optional)
-
-```javascript
-// Default skin
-import "@appsbd/vue3-appsbd-ui/dist/skins/default.css";
-
-// Or any other prebuilt skin
-import "@appsbd/vue3-appsbd-ui/dist/skins/purple.css";
-```
-
-## 🧩 Core Components & Composables
-
-### Toast Notifications
-
-The library includes a robust custom toast system with pause-on-hover and pause-on-focus-loss features.
-
-```javascript
-import { useToast } from "@appsbd/vue3-appsbd-ui";
-const { toast } = useToast();
-
-toast.success("Changes saved!", { timeout: 3000 });
-toast.error("An error occurred", { position: "top-center" });
-```
-
-### Global Alerts
-
-Integrated SweetAlert2 system focused on aesthetic consistency.
-
-```javascript
-import { useAlert } from "@appsbd/vue3-appsbd-ui";
-const { alert } = useAlert();
-
-alert.success("Success!", "Your profile has been updated.");
-```
-
-### Theme Management
-
-Easily toggle between light and dark modes.
-
-```javascript
-import { useTheme } from "@appsbd/vue3-appsbd-ui";
-const { isDark, toggleTheme } = useTheme();
-```
-
-## 📚 Component Reference
-
-| Component                                                 | Description                                                                                       |
-| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `AbAvatar`                                                | Profile imagery with status indicators and size variants.                                         |
-| `AbBadge`                                                 | Labeling component for status and counts.                                                         |
-| `AbButton`                                                | Highly customizable button with loading states.                                                   |
-| `AbCard`                                                  | Flexible container for grouped content (supports tile / item / insight variants via CSS classes). |
-| `AbCarousel`                                              | Responsive carousel / slider.                                                                     |
-| `AbColorPicker`                                           | Visual color selection interface.                                                                 |
-| `AbConfirmPopover`                                        | Multi-step interactive popover for confirmations and async flows.                                 |
-| `AbCustomField`                                           | Base wrapper for creating custom form inputs.                                                     |
-| `AbDarkModeToggler`                                       | One-click light/dark theme toggle.                                                                |
-| `AbDateTimePicker`                                        | Full-featured date and time selection (powered by v-calendar).                                    |
-| `AbDropdown`                                              | Custom styled dropdown menus.                                                                     |
-| `AbEasyModal`                                             | Lightweight modal for simple dialogs.                                                             |
-| `AbField`                                                 | Generic form field wrapper with label / help / error slots.                                       |
-| `AbFileUploader`                                          | Drag-and-drop file upload interface.                                                              |
-| `AbFilterPanel`                                           | Comprehensive filtering UI for data-heavy views.                                                  |
-| `AbFormCheck` / `AbRadioInput`                            | Standardized checkbox / radio controls.                                                           |
-| `AbImageRadioInput`                                       | Radio group rendered as selectable image tiles.                                                   |
-| `AbInputField`                                            | High-quality text input with validation/feedback.                                                 |
-| `AbInputTag`                                              | Tagging / multiple-value input field.                                                             |
-| `AbKbd` / `AbKbdGroup`                                    | Keyboard shortcut display primitives.                                                             |
-| `AbModal`                                                 | Sophisticated dialog system with transitions.                                                     |
-| `AbMultiSelect`                                           | Advanced searchable multi-selection dropdown (built-in, replaces `@vueform/multiselect`).         |
-| `AbNavLink`                                               | Navigation link for sidebars and menus.                                                           |
-| `AbNumberField`                                           | Numeric input with step controls.                                                                 |
-| `AbPinInput`                                              | Segmented OTP / PIN entry input.                                                                  |
-| `AbPopover`                                               | Floating popover powered by floating-vue.                                                         |
-| `AbPricingCard` / `AbPricingContainer` / `AbPricingTable` | Composable pricing-plan building blocks.                                                          |
-| `AbProgressbar`                                           | Smooth, animated progress tracking.                                                               |
-| `AbScrollbar`                                             | Styled custom scroll container.                                                                   |
-| `AbSettingsForm`                                          | Opinionated settings / preferences form layout.                                                   |
-| `AbSidebar` / `AbSideMenuItem`                            | Dynamic sidebar navigation components.                                                            |
-| `AbSkeleton`                                              | Loading-state skeleton placeholders.                                                              |
-| `AbSlider`                                                | Range selection slider for numerical values.                                                      |
-| `AbTable`                                                 | Data table with the project's default styling.                                                    |
-| `AbTabs` / `AbTab`                                        | Responsive tabbed interface.                                                                      |
-| `AbToast`                                                 | High-performance notification system.                                                             |
-| `AbToggle`                                                | Accessible switch/toggle component.                                                               |
-| `AbTooltip`                                               | Floating tooltip powered by floating-vue.                                                         |
-| `AbWizard` / `AbWizardStep`                               | Multi-step wizard flow.                                                                           |
-
-## 📄 License
-
-MIT
+# Vue 3 Appsbd UI Library
+
+A premium, reusable Vue 3 component library built for high-performance enterprise applications. Leverages **Vite**, **SCSS**, and **Bootstrap 5** to provide a rich set of UI components with built-in Dark Mode and RTL support.
+
+## 🚀 Key Features
+
+- **Vue 3 Composition API**: Optimized for performance and flexibility.
+- **Dynamic Theming**: Full dark mode support using Bootstrap's `data-bs-theme`.
+- **RTL Ready**: Built with CSS logical properties for global accessibility.
+- **Plugin System**: custom-built global systems for Toasts and Alerts.
+- **Enterprise Ready**: Includes complex components like MultiSelect, DatePicker, Wizard, Pricing Tables, and Filter Panels.
+- **Themable Skins**: 10 prebuilt color skins (default, green, red, cyan, purple, violet, pink, orange, gray, black) shipped as standalone CSS under `dist/skins/`.
+
+## 📦 Installation
+
+```bash
+npm install @appsbd/vue3-appsbd-ui
+```
+
+### Peer Dependencies
+
+Ensure you have the following installed in your project:
+
+```bash
+npm install bootstrap bootstrap-icons vee-validate @vee-validate/rules vue-router vue3-gettext lucide-vue-next tiny-emitter @appsbd/vue3-elite-grid
+```
+
+## 🤖 AI Assistant Integration
+
+Installing this library automatically copies AI skills into your project so Claude Code and Agent-based tools can generate correct component code without guessing props or imports.
+
+### What gets installed
+
+Running `npm install @appsbd/vue3-appsbd-ui` copies the following automatically:
+
+| Destination | Purpose |
+| --- | --- |
+| `.claude/commands/` | Slash commands for Claude Code (`/use-appsbd-ui`, `/generate-module`) |
+| `.claude/skills/` | Skills auto-detected by Claude Code |
+| `.agent/workflows/` | Workflow commands for Agent-based tools |
+| `.agent/skills/` | Skills for Agent-based tools |
+
+### Available slash commands
+
+| Command | Description |
+| --- | --- |
+| `/use-appsbd-ui` | Loads component reference before generating any code — always run this first |
+| `/generate-module` | Scaffolds a full CRUD module (List + Form + Composable) for a given entity |
+
+**Example:**
+```
+/generate-module
+
+Module: Invoice
+Fields:
+- title (text, required)
+- amount (number, required, min: 0)
+- status (select: Draft | Sent | Paid, required)
+- due_date (date)
+
+API: /api/invoices
+Output: src/modules/invoices/
+```
+
+### Optional: enable additional AI tools
+
+To also install skills for Cursor or Windsurf, pass `APPSBD_AGENTS` during install:
+
+```bash
+APPSBD_AGENTS=cursor npm install @appsbd/vue3-appsbd-ui
+APPSBD_AGENTS=cursor,windsurf npm install @appsbd/vue3-appsbd-ui
+```
+
+Or run the setup script any time after install:
+
+```bash
+node node_modules/@appsbd/vue3-appsbd-ui/scripts/setup.js --cursor --windsurf
+```
+
+### Manual reference
+
+If you prefer not to use auto-installed skills, the reference files are included in the package:
+
+- `node_modules/@appsbd/vue3-appsbd-ui/AI_REF.md` — compact component index (~500 tokens, start here)
+- `node_modules/@appsbd/vue3-appsbd-ui/AI_REFERENCE.md` — full table with descriptions
+- `node_modules/@appsbd/vue3-appsbd-ui/.ai/ai_ref_[Name].md` — per-component props/events/slots
+
+Point your AI to read `AI_REF.md` first, then the specific `.ai/` file for the component you need.
+
+## 🛠️ Setup
+
+Register the library and its styles in your main entry file (e.g., `main.js`):
+
+```javascript
+import { createApp } from "vue";
+import AppsbdUI from "@appsbd/vue3-appsbd-ui";
+import "@appsbd/vue3-appsbd-ui/style.css";
+
+const app = createApp(App);
+app.use(AppsbdUI);
+app.mount("#app");
+```
+
+### Applying a Theme Skin (optional)
+
+```javascript
+// Default skin
+import "@appsbd/vue3-appsbd-ui/dist/skins/default.css";
+
+// Or any other prebuilt skin
+import "@appsbd/vue3-appsbd-ui/dist/skins/purple.css";
+```
+
+## 🧩 Core Components & Composables
+
+### Toast Notifications
+
+The library includes a robust custom toast system with pause-on-hover and pause-on-focus-loss features.
+
+```javascript
+import { useToast } from "@appsbd/vue3-appsbd-ui";
+const { toast } = useToast();
+
+toast.success("Changes saved!", { timeout: 3000 });
+toast.error("An error occurred", { position: "top-center" });
+```
+
+### Global Alerts
+
+Integrated SweetAlert2 system focused on aesthetic consistency.
+
+```javascript
+import { useAlert } from "@appsbd/vue3-appsbd-ui";
+const { alert } = useAlert();
+
+alert.success("Success!", "Your profile has been updated.");
+```
+
+### Theme Management
+
+Easily toggle between light and dark modes.
+
+```javascript
+import { useTheme } from "@appsbd/vue3-appsbd-ui";
+const { isDark, toggleTheme } = useTheme();
+```
+
+## 📚 Component Reference
+
+| Component                                                 | Description                                                                                       |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `AbAvatar`                                                | Profile imagery with status indicators and size variants.                                         |
+| `AbBadge`                                                 | Labeling component for status and counts.                                                         |
+| `AbButton`                                                | Highly customizable button with loading states.                                                   |
+| `AbCard`                                                  | Flexible container for grouped content (supports tile / item / insight variants via CSS classes). |
+| `AbCarousel`                                              | Responsive carousel / slider.                                                                     |
+| `AbColorPicker`                                           | Visual color selection interface.                                                                 |
+| `AbConfirmPopover`                                        | Multi-step interactive popover for confirmations and async flows.                                 |
+| `AbCustomField`                                           | Base wrapper for creating custom form inputs.                                                     |
+| `AbDarkModeToggler`                                       | One-click light/dark theme toggle.                                                                |
+| `AbDateTimePicker`                                        | Full-featured date and time selection (powered by v-calendar).                                    |
+| `AbDropdown`                                              | Custom styled dropdown menus.                                                                     |
+| `AbEasyModal`                                             | Lightweight modal for simple dialogs.                                                             |
+| `AbField`                                                 | Generic form field wrapper with label / help / error slots.                                       |
+| `AbFileUploader`                                          | Drag-and-drop file upload interface.                                                              |
+| `AbFilterPanel`                                           | Comprehensive filtering UI for data-heavy views.                                                  |
+| `AbFormCheck` / `AbRadioInput`                            | Standardized checkbox / radio controls.                                                           |
+| `AbImageRadioInput`                                       | Radio group rendered as selectable image tiles.                                                   |
+| `AbInputField`                                            | High-quality text input with validation/feedback.                                                 |
+| `AbInputTag`                                              | Tagging / multiple-value input field.                                                             |
+| `AbKbd` / `AbKbdGroup`                                    | Keyboard shortcut display primitives.                                                             |
+| `AbModal`                                                 | Sophisticated dialog system with transitions.                                                     |
+| `AbMultiSelect`                                           | Advanced searchable multi-selection dropdown (built-in, replaces `@vueform/multiselect`).         |
+| `AbNavLink`                                               | Navigation link for sidebars and menus.                                                           |
+| `AbNumberField`                                           | Numeric input with step controls.                                                                 |
+| `AbPinInput`                                              | Segmented OTP / PIN entry input.                                                                  |
+| `AbPopover`                                               | Floating popover powered by floating-vue.                                                         |
+| `AbPricingCard` / `AbPricingContainer` / `AbPricingTable` | Composable pricing-plan building blocks.                                                          |
+| `AbProgressbar`                                           | Smooth, animated progress tracking.                                                               |
+| `AbScrollbar`                                             | Styled custom scroll container.                                                                   |
+| `AbSettingsForm`                                          | Opinionated settings / preferences form layout.                                                   |
+| `AbSidebar` / `AbSideMenuItem`                            | Dynamic sidebar navigation components.                                                            |
+| `AbSkeleton`                                              | Loading-state skeleton placeholders.                                                              |
+| `AbSlider`                                                | Range selection slider for numerical values.                                                      |
+| `AbTable`                                                 | Data table with the project's default styling.                                                    |
+| `AbTabs` / `AbTab`                                        | Responsive tabbed interface.                                                                      |
+| `AbToast`                                                 | High-performance notification system.                                                             |
+| `AbToggle`                                                | Accessible switch/toggle component.                                                               |
+| `AbTooltip`                                               | Floating tooltip powered by floating-vue.                                                         |
+| `AbWizard` / `AbWizardStep`                               | Multi-step wizard flow.                                                                           |
+
+## 📄 License
+
+MIT

package/scripts/postinstall.js

@@ -0,0 +1,55 @@
+import { existsSync, mkdirSync, copyFileSync, readFileSync, readdirSync } from "fs";
+import { join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { getSkillGroups } from "./skill-groups.js";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const pkgRoot = resolve(__dirname, "..");
+
+// INIT_CWD = directory where `npm install` was invoked (consuming project root).
+const projectRoot = process.env.INIT_CWD || resolve(__dirname, "../../../..");
+
+// Skip when the library is installing its own devDependencies.
+try {
+  const pkg = JSON.parse(readFileSync(join(projectRoot, "package.json"), "utf8"));
+  if (pkg.name === "@appsbd/vue3-appsbd-ui") process.exit(0);
+} catch {
+  // consuming project has no package.json at that path — continue anyway
+}
+
+// Optional agents: APPSBD_AGENTS=cursor,windsurf npm install @appsbd/vue3-appsbd-ui
+const agents = process.env.APPSBD_AGENTS
+  ? process.env.APPSBD_AGENTS.split(",").map((a) => a.trim().toLowerCase())
+  : [];
+
+try {
+  copySkills(pkgRoot, projectRoot, agents);
+} catch (err) {
+  // Non-fatal — never break npm install
+  console.warn("[@appsbd/vue3-appsbd-ui] Could not install skills:", err.message);
+}
+
+export function copySkills(pkgRoot, projectRoot, agents = []) {
+  const groups = getSkillGroups(pkgRoot, projectRoot, agents);
+  let copied = 0, skipped = 0;
+
+  for (const group of groups) {
+    if (!existsSync(group.src)) continue;
+    const files = readdirSync(group.src).filter((f) => f.endsWith(".md"));
+
+    for (const dest of group.dests) {
+      if (!existsSync(dest)) mkdirSync(dest, { recursive: true });
+      for (const file of files) {
+        const dst = join(dest, file);
+        if (group.override.includes(file) || !existsSync(dst)) {
+          copyFileSync(join(group.src, file), dst);
+          copied++;
+        } else {
+          skipped++;
+        }
+      }
+    }
+  }
+
+  console.log(`[@appsbd/vue3-appsbd-ui] Skills → copied: ${copied}, skipped (preserved): ${skipped}`);
+}

package/scripts/setup.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// Usage: node node_modules/@appsbd/vue3-appsbd-ui/scripts/setup.js --cursor --windsurf
+
+import { resolve } from "path";
+import { fileURLToPath } from "url";
+import { copySkills } from "./postinstall.js";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const pkgRoot = resolve(__dirname, "..");
+const projectRoot = process.env.INIT_CWD || process.cwd();
+
+const agents = process.argv
+  .filter((a) => a.startsWith("--"))
+  .map((a) => a.slice(2).toLowerCase());
+
+copySkills(pkgRoot, projectRoot, agents);

package/scripts/skill-groups.js

@@ -0,0 +1,38 @@
+import { join } from "path";
+
+// Central config for all agent skill destinations.
+// Add new agents here — postinstall.js and setup.js both use this.
+
+const OPTIONAL_AGENTS = {
+  cursor: (pkgRoot, projectRoot) => [
+    { src: join(pkgRoot, "skills", "commands"), dests: [join(projectRoot, ".cursor", "rules")], override: ["use-appsbd-ui.md"] },
+    { src: join(pkgRoot, "skills", "skills"),   dests: [join(projectRoot, ".cursor", "rules")], override: [] },
+  ],
+  windsurf: (pkgRoot, projectRoot) => [
+    { src: join(pkgRoot, "skills", "commands"), dests: [join(projectRoot, ".windsurf", "workflows")], override: ["use-appsbd-ui.md"] },
+    { src: join(pkgRoot, "skills", "skills"),   dests: [join(projectRoot, ".windsurf", "rules")],     override: [] },
+  ],
+};
+
+export function getSkillGroups(pkgRoot, projectRoot, agents = []) {
+  const groups = [
+    // Always installed — Claude Code + Agent
+    {
+      src: join(pkgRoot, "skills", "commands"),
+      dests: [join(projectRoot, ".claude", "commands"), join(projectRoot, ".agent", "workflows")],
+      override: ["use-appsbd-ui.md"],
+    },
+    {
+      src: join(pkgRoot, "skills", "skills"),
+      dests: [join(projectRoot, ".claude", "skills"), join(projectRoot, ".agent", "skills")],
+      override: [],
+    },
+  ];
+
+  for (const agent of agents) {
+    if (OPTIONAL_AGENTS[agent]) groups.push(...OPTIONAL_AGENTS[agent](pkgRoot, projectRoot));
+    else console.warn(`[@appsbd/vue3-appsbd-ui] Unknown agent "${agent}" — skipped. Available: ${Object.keys(OPTIONAL_AGENTS).join(", ")}`);
+  }
+
+  return groups;
+}