first

.agents/skills/antfu/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: antfu
+description: Anthony Fu's {Opinionated} preferences and best practices for web development
+metadata:
+  author: Anthony Fu
+  version: "2026.1.28"
+---
+
+# Anthony Fu's Preferences
+
+This skill covers Anthony Fu's preferred tooling, configurations, and best practices for web development. This skill is opinionated.
+
+## Quick Summary
+
+| Category | Preference |
+|----------|------------|
+| Package Manager | pnpm |
+| Language | TypeScript (strict mode) |
+| Module System | ESM (`"type": "module"`) |
+| Linting & Formatting | @antfu/eslint-config (no Prettier) |
+| Testing | Vitest |
+| Git Hooks | simple-git-hooks + lint-staged |
+| Documentation | VitePress (in `docs/`) |
+
+---
+
+## Core Stack
+
+### Package Manager (pnpm)
+
+Use pnpm as the package manager.
+
+For monorepo setups, use pnpm workspaces:
+
+```yaml
+# pnpm-workspace.yaml
+packages:
+  - 'packages/*'
+```
+
+
+Use pnpm named catalogs in `pnpm-workspace.yaml` to manage dependency versions:
+
+| Catalog | Purpose |
+|---------|---------|
+| `prod` | Production dependencies |
+| `inlined` | Dependencies inlined by bundler |
+| `dev` | Development tools (linter, bundler, testing, dev-server) |
+| `frontend` | Frontend libraries bundled into frontend |
+
+Catalog names are not limited to the above and can be adjusted based on needs. Avoid using default catalog.
+
+#### @antfu/ni
+
+Use `@antfu/ni` for unified package manager commands. It auto-detects the package manager (pnpm/npm/yarn/bun) based on lockfile.
+
+| Command | Description |
+|---------|-------------|
+| `ni` | Install dependencies |
+| `ni <pkg>` | Add dependency |
+| `ni -D <pkg>` | Add dev dependency |
+| `nr <script>` | Run script |
+| `nu` | Upgrade dependencies |
+| `nun <pkg>` | Uninstall dependency |
+| `nci` | Clean install (like `pnpm i --frozen-lockfile`) |
+| `nlx <pkg>` | Execute package (like `npx`) |
+
+Install globally with `pnpm i -g @antfu/ni` if the commands are not found.
+
+### TypeScript (Strict Mode)
+
+Always use TypeScript with strict mode enabled.
+
+```json
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true
+  }
+}
+```
+
+### ESM (ECMAScript Modules)
+
+Always work in ESM mode. Set `"type": "module"` in `package.json`.
+
+---
+
+## Code Quality
+
+### ESLint (@antfu/eslint-config)
+
+Use `@antfu/eslint-config` for both formatting and linting. This eliminates the need for Prettier.
+
+Create `eslint.config.js` with `// @ts-check` comment:
+
+```js
+// @ts-check
+import antfu from '@antfu/eslint-config'
+
+export default antfu()
+```
+
+Add script to `package.json`:
+
+```json
+{
+  "scripts": {
+    "lint": "eslint ."
+  }
+}
+```
+
+When getting linting errors, try to fix them with `nr lint --fix`. Don't add `lint:fix` script.
+
+### Git Hooks (simple-git-hooks + lint-staged)
+
+Use `simple-git-hooks` with `lint-staged` for pre-commit linting:
+
+```json
+{
+  "simple-git-hooks": {
+    "pre-commit": "pnpm i --frozen-lockfile --ignore-scripts --offline && npx lint-staged"
+  },
+  "lint-staged": {
+    "*": "eslint --fix"
+  },
+  "scripts": {
+    "prepare": "npx simple-git-hooks"
+  }
+}
+```
+
+### Unit Testing (Vitest)
+
+Use Vitest for unit testing.
+
+```json
+{
+  "scripts": {
+    "test": "vitest"
+  }
+}
+```
+
+**Conventions:**
+
+- Place test files next to source files: `foo.ts` → `foo.test.ts` (same directory)
+- High-level tests go in `tests/` directory in each package
+- Use `describe` and `it` API (not `test`)
+- Use `expect` API for assertions
+- Use `assert` only for TypeScript null assertions
+- Use `toMatchSnapshot` for complex output assertions
+- Use `toMatchFileSnapshot` with explicit file path and extension for language-specific output (exclude those files from linting)
+
+---
+
+## Project Setup
+
+### Publishing (Library Projects)
+
+For library projects, publish through GitHub Releases triggered by `bumpp`:
+
+```json
+{
+  "scripts": {
+    "release": "bumpp -r"
+  }
+}
+```
+
+### Documentation (VitePress)
+
+Use VitePress for documentation. Place docs under `docs/` directory.
+
+```
+docs/
+├── .vitepress/
+│   └── config.ts
+├── index.md
+└── guide/
+    └── getting-started.md
+```
+
+Add script to `package.json`:
+
+```json
+{
+  "scripts": {
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs"
+  }
+}
+```
+
+---
+
+## References
+
+### Project Setup
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| @antfu/eslint-config | ESLint flat config for formatting and linting | [antfu-eslint-config](references/antfu-eslint-config.md) |
+| GitHub Actions | Preferred workflows using sxzz/workflows | [github-actions](references/github-actions.md) |
+| .gitignore | Preferred .gitignore for JS/TS projects | [gitignore](references/gitignore.md) |
+| VS Code Extensions | Recommended extensions for development | [vscode-extensions](references/vscode-extensions.md) |
+
+### Development
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| App Development | Preferences for Vue/Vite/Nuxt/UnoCSS web applications | [app-development](references/app-development.md) |
+| Library Development | Preferences for bundling and publishing TypeScript libraries | [library-development](references/library-development.md) |
+| Monorepo | pnpm workspaces, centralized alias, Turborepo | [monorepo](references/monorepo.md) |

.agents/skills/antfu/references/antfu-eslint-config.md

@@ -0,0 +1,328 @@
+---
+name: antfu-eslint-config
+description: ESLint flat config for formatting and linting - replaces Prettier
+---
+
+# @antfu/eslint-config
+
+A comprehensive ESLint flat config that handles both linting and formatting. Designed to replace Prettier entirely.
+
+## Key Characteristics
+
+- **No Prettier needed** - Handles all formatting via ESLint
+- **ESLint Flat config** - Uses the new `eslint.config.js` format
+- **Auto-detection** - TypeScript and Vue are detected automatically
+- **Style principle**: Single quotes, no semicolons, sorted imports, dangling commas
+- **Respects `.gitignore`** by default
+
+## Basic Configuration
+
+Create `eslint.config.mjs` (or `eslint.config.js` with `// @ts-check`):
+
+```js
+// eslint.config.mjs
+import antfu from '@antfu/eslint-config'
+
+export default antfu()
+```
+
+Add scripts to `package.json`:
+
+```json
+{
+  "scripts": {
+    "lint": "eslint"
+  }
+}
+```
+
+## Configuration Options
+
+```js
+import antfu from '@antfu/eslint-config'
+
+export default antfu({
+  // Project type: 'lib' for libraries, 'app' (default) for applications
+  type: 'lib',
+
+  // Global ignores (extends defaults, doesn't override)
+  ignores: ['**/fixtures', '**/dist'],
+
+  // Stylistic options
+  stylistic: {
+    indent: 2,        // 2, 4, or 'tab'
+    quotes: 'single', // or 'double'
+  },
+
+  // Framework support (auto-detected, but can be explicit)
+  typescript: true,
+  vue: true,
+
+  // Disable specific language support
+  jsonc: false,
+  yaml: false,
+})
+```
+
+## Framework Support
+
+### Vue
+
+Vue accessibility:
+
+```js
+export default antfu({
+  vue: {
+    a11y: true
+  },
+})
+// Requires: pnpm add -D eslint-plugin-vuejs-accessibility
+```
+
+### React
+
+```js
+export default antfu({
+  react: true,
+})
+// Requires: pnpm add -D @eslint-react/eslint-plugin eslint-plugin-react-hooks eslint-plugin-react-refresh
+```
+
+### Next.js
+
+```js
+export default antfu({
+  nextjs: true,
+})
+// Requires: pnpm add -D @next/eslint-plugin-next
+```
+
+### Svelte
+
+```js
+export default antfu({
+  svelte: true,
+})
+// Requires: pnpm add -D eslint-plugin-svelte
+```
+
+### Astro
+
+```js
+export default antfu({
+  astro: true,
+})
+// Requires: pnpm add -D eslint-plugin-astro
+```
+
+### Solid
+
+```js
+export default antfu({
+  solid: true,
+})
+// Requires: pnpm add -D eslint-plugin-solid
+```
+
+### UnoCSS
+
+```js
+export default antfu({
+  unocss: true,
+})
+// Requires: pnpm add -D @unocss/eslint-plugin
+```
+
+## Formatters (CSS, HTML, Markdown)
+
+For files ESLint doesn't handle natively:
+
+```js
+export default antfu({
+  formatters: {
+    css: true,      // Format CSS, LESS, SCSS (uses Prettier)
+    html: true,     // Format HTML (uses Prettier)
+    markdown: 'prettier' // or 'dprint'
+  }
+})
+// Requires: pnpm add -D eslint-plugin-format
+```
+
+## Rule Overrides
+
+### Global overrides
+
+```js
+export default antfu(
+  {
+    // First argument: antfu config options
+  },
+  // Additional arguments: ESLint flat configs
+  {
+    rules: {
+      'style/semi': ['error', 'never'],
+    },
+  }
+)
+```
+
+### Per-integration overrides
+
+```js
+export default antfu({
+  vue: {
+    overrides: {
+      'vue/operator-linebreak': ['error', 'before'],
+    },
+  },
+  typescript: {
+    overrides: {
+      'ts/consistent-type-definitions': ['error', 'interface'],
+    },
+  },
+})
+```
+
+### File-specific overrides
+
+```js
+export default antfu(
+  { vue: true, typescript: true },
+  {
+    files: ['**/*.vue'],
+    rules: {
+      'vue/operator-linebreak': ['error', 'before'],
+    },
+  }
+)
+```
+
+## Plugin Prefix Renaming
+
+The config renames plugin prefixes for consistency:
+
+| New Prefix | Original |
+|------------|----------|
+| `ts/*` | `@typescript-eslint/*` |
+| `style/*` | `@stylistic/*` |
+| `import/*` | `import-lite/*` |
+| `node/*` | `n/*` |
+| `yaml/*` | `yml/*` |
+| `test/*` | `vitest/*` |
+| `next/*` | `@next/next` |
+
+Use the new prefix when overriding or disabling rules:
+
+```ts
+// eslint-disable-next-line ts/consistent-type-definitions
+type Foo = { bar: 2 }
+```
+
+## Type-Aware Rules
+
+Enable TypeScript type checking:
+
+```js
+export default antfu({
+  typescript: {
+    tsconfigPath: 'tsconfig.json',
+  },
+})
+```
+
+## Config Composer API
+
+Chain methods for flexible composition:
+
+```js
+export default antfu()
+  .prepend(/* configs before main */)
+  .override('antfu/stylistic/rules', {
+    rules: {
+      'style/generator-star-spacing': ['error', { after: true, before: false }],
+    }
+  })
+  .renamePlugins({
+    'old-prefix': 'new-prefix',
+  })
+```
+
+## Less Opinionated Mode
+
+Disable Anthony's most opinionated rules:
+
+```js
+export default antfu({
+  lessOpinionated: true
+})
+```
+
+## Lint-Staged Setup
+
+```json
+{
+  "simple-git-hooks": {
+    "pre-commit": "pnpm lint-staged"
+  },
+  "lint-staged": {
+    "*": "eslint --fix"
+  }
+}
+```
+
+```bash
+pnpm add -D lint-staged simple-git-hooks
+npx simple-git-hooks
+```
+
+## VS Code Settings
+
+Add to `.vscode/settings.json`:
+
+```jsonc
+{
+  "prettier.enable": false,
+  "editor.formatOnSave": false,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit",
+    "source.organizeImports": "never"
+  },
+  "eslint.rules.customizations": [
+    { "rule": "style/*", "severity": "off", "fixable": true },
+    { "rule": "format/*", "severity": "off", "fixable": true },
+    { "rule": "*-indent", "severity": "off", "fixable": true },
+    { "rule": "*-spacing", "severity": "off", "fixable": true },
+    { "rule": "*-spaces", "severity": "off", "fixable": true },
+    { "rule": "*-order", "severity": "off", "fixable": true },
+    { "rule": "*-dangle", "severity": "off", "fixable": true },
+    { "rule": "*-newline", "severity": "off", "fixable": true },
+    { "rule": "*quotes", "severity": "off", "fixable": true },
+    { "rule": "*semi", "severity": "off", "fixable": true }
+  ],
+  "eslint.validate": [
+    "javascript",
+    "javascriptreact",
+    "typescript",
+    "typescriptreact",
+    "vue",
+    "html",
+    "markdown",
+    "json",
+    "jsonc",
+    "yaml",
+    "toml",
+    "xml",
+    "astro",
+    "svelte",
+    "css",
+    "less",
+    "scss"
+  ]
+}
+```
+
+<!-- 
+Source references:
+- https://github.com/antfu/eslint-config
+- https://raw.githubusercontent.com/antfu/eslint-config/refs/heads/main/README.md
+-->

.agents/skills/antfu/references/app-development.md

@@ -0,0 +1,60 @@
+---
+name: app-development
+description: Anthony Fu's preferences for building web applications with Vue, Vite/Nuxt, and UnoCSS
+---
+
+# App Development Preferences
+
+Preferences for building web applications.
+
+## Stack Overview
+
+| Aspect | Choice |
+|--------|--------|
+| Framework | Vue 3 (Composition API) |
+| Build Tool | Vite (SPA) or Nuxt (SSR/SSG) |
+| Styling | UnoCSS |
+| Utilities | VueUse |
+
+---
+
+## Framework Selection
+
+| Use Case | Choice |
+|----------|--------|
+| SPA, client-only, library playgrounds | Vite + Vue |
+| SSR, SSG, SEO-critical, file-based routing, API routes | Nuxt |
+
+---
+
+## Vue Conventions
+
+| Convention | Preference |
+|------------|------------|
+| Script syntax | Always `<script setup lang="ts">` |
+| State | Prefer `shallowRef()` over `ref()` |
+| Objects | Use `ref()`, avoid `reactive()` |
+
+### Props and Emits
+
+Use TypeScript interfaces:
+
+```vue
+<script setup lang="ts">
+interface Props {
+  title: string
+  count?: number
+}
+
+interface Emits {
+  (e: 'update', value: number): void
+  (e: 'close'): void
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  count: 0,
+})
+
+const emit = defineEmits<Emits>()
+</script>
+```

.agents/skills/antfu/references/github-actions.md

@@ -0,0 +1,68 @@
+---
+name: github-actions
+description: Anthony Fu's preferred GitHub Actions workflows using sxzz/workflows
+---
+
+# GitHub Actions
+
+When setting up a new project, add these workflows. Skip if workflows already exist.
+
+## Autofix Workflow
+
+**`.github/workflows/autofix.yml`** - Auto-fix linting on PRs:
+
+```yaml
+name: autofix.ci
+
+on: [pull_request]
+
+jobs:
+  autofix:
+    uses: sxzz/workflows/.github/workflows/autofix.yml@v1
+    permissions:
+      contents: read
+```
+
+## Unit Test Workflow
+
+**`.github/workflows/unit-test.yml`** - Run tests on push/PR:
+
+```yaml
+name: Unit Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions: {}
+
+jobs:
+  unit-test:
+    uses: sxzz/workflows/.github/workflows/unit-test.yml@v1
+```
+
+## Release Workflow
+
+**`.github/workflows/release.yml`** - Publish on tag (library projects only):
+
+```yaml
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    uses: sxzz/workflows/.github/workflows/release.yml@v1
+    with:
+      publish: true
+    permissions:
+      contents: write
+      id-token: write
+```
+
+All workflows use [sxzz/workflows](https://github.com/sxzz/workflows) reusable workflows.

.agents/skills/antfu/references/gitignore.md

@@ -0,0 +1,29 @@
+---
+name: gitignore
+description: Anthony Fu's preferred .gitignore for JavaScript/TypeScript projects
+---
+
+# .gitignore
+
+When `.gitignore` is not present, create it with:
+
+```
+*.log
+*.tgz
+.cache
+.DS_Store
+.eslintcache
+.idea
+.env
+.nuxt
+.temp
+.output
+.turbo
+cache
+coverage
+dist
+lib-cov
+logs
+node_modules
+temp
+```

.agents/skills/antfu/references/library-development.md

@@ -0,0 +1,85 @@
+---
+name: library-development
+description: Anthony Fu's preferences for building and publishing JavaScript/TypeScript libraries
+---
+
+# Library Development Preferences
+
+Preferences for bundling and publishing TypeScript libraries.
+
+## Key Decisions
+
+| Aspect | Choice |
+|--------|--------|
+| Bundler | tsdown |
+| Output | Pure ESM only (no CJS) |
+| DTS | Generated via tsdown |
+| Exports | Auto-generated via tsdown |
+
+---
+
+## tsdown Configuration
+
+Use tsdown with these options enabled:
+
+```ts
+// tsdown.config.ts
+import { defineConfig } from 'tsdown'
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  exports: true,
+})
+```
+
+| Option | Value | Purpose |
+|--------|-------|---------|
+| `format` | `['esm']` | Pure ESM, no CommonJS |
+| `dts` | `true` | Generate `.d.ts` files |
+| `exports` | `true` | Auto-update `exports` field in `package.json` |
+
+### Multiple Entry Points
+
+```ts
+export default defineConfig({
+  entry: [
+    'src/index.ts',
+    'src/utils.ts',
+  ],
+  format: ['esm'],
+  dts: true,
+  exports: true,
+})
+```
+
+The `exports: true` option auto-generates the `exports` field in `package.json` when running `tsdown`.
+
+---
+
+## package.json
+
+Required fields for pure ESM library:
+
+```json
+{
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsdown",
+    "prepack": "pnpm build",
+    "test": "vitest",
+    "release": "bumpp -r"
+  }
+}
+```
+
+The `exports` field is managed by tsdown when `exports: true`.
+
+### prepack Script
+
+For each public package, add `"prepack": "pnpm build"` to `scripts`. This ensures the package is automatically built before publishing (e.g., when running `npm publish` or `pnpm publish`). This prevents accidentally publishing stale or missing build artifacts.

.agents/skills/antfu/references/monorepo.md

@@ -0,0 +1,126 @@
+---
+name: monorepo
+description: Anthony Fu's monorepo setup conventions using pnpm workspaces
+---
+
+# Monorepo Setup
+
+Conventions for setting up and managing monorepos.
+
+## pnpm Workspaces
+
+Use pnpm workspaces for monorepo management:
+
+```yaml
+# pnpm-workspace.yaml
+packages:
+  - 'packages/*'
+```
+
+## Scripts Convention
+
+Have scripts in each package, and use `-r` (recursive) flag at root,
+Enable ESLint cache for faster linting in monorepos.
+
+```json
+// root package.json
+{
+  "scripts": {
+    "build": "pnpm run -r build",
+    "test": "vitest",
+    "lint": "eslint . --cache --concurrency=auto"
+  }
+}
+```
+
+In each package's `package.json`, add the scripts.
+
+```json
+// packages/*/package.json
+{
+  "scripts": {
+    "build": "tsdown",
+    "prepack": "pnpm build"
+  }
+}
+```
+
+## ESLint Cache
+
+
+```json
+{
+  "scripts": {
+    "lint": "eslint . --cache --concurrency=auto"
+  }
+}
+```
+
+## Turborepo (Optional)
+
+For monorepos with many packages or long build times, use Turborepo for task orchestration and caching.
+
+See the dedicated Turborepo skill for detailed configuration.
+
+## Centralized Alias
+
+For better DX across Vite, Nuxt, Vitest configs, create a centralized `alias.ts` at project root:
+
+```ts
+// alias.ts
+import fs from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join, relative } from 'pathe'
+
+const root = fileURLToPath(new URL('.', import.meta.url))
+const r = (path: string) => fileURLToPath(new URL(`./packages/${path}`, import.meta.url))
+
+export const alias = {
+  '@myorg/core': r('core/src/index.ts'),
+  '@myorg/utils': r('utils/src/index.ts'),
+  '@myorg/ui': r('ui/src/index.ts'),
+  // Add more aliases as needed
+}
+
+// Auto-update tsconfig.alias.json paths
+const raw = fs.readFileSync(join(root, 'tsconfig.alias.json'), 'utf-8').trim()
+const tsconfig = JSON.parse(raw)
+tsconfig.compilerOptions.paths = Object.fromEntries(
+  Object.entries(alias).map(([key, value]) => [key, [`./${relative(root, value)}`]]),
+)
+const newRaw = JSON.stringify(tsconfig, null, 2)
+if (newRaw !== raw)
+  fs.writeFileSync(join(root, 'tsconfig.alias.json'), `${newRaw}\n`, 'utf-8')
+```
+
+Then update the `tsconfig.json` to use the alias file:
+
+```json
+{
+  "extends": [
+    "./tsconfig.alias.json"
+  ]
+}
+```
+
+### Using Alias in Configs
+
+Reference the centralized alias in all config files:
+
+```ts
+// vite.config.ts
+import { alias } from './alias'
+
+export default defineConfig({
+  resolve: { alias },
+})
+```
+
+```ts
+// nuxt.config.ts
+import { alias } from './alias'
+
+export default defineNuxtConfig({
+  alias,
+})
+```

.agents/skills/antfu/references/vscode-extensions.md

@@ -0,0 +1,34 @@
+---
+name: vscode-extensions
+description: Recommended VS Code extensions
+---
+
+# VS Code Extensions
+
+## Recommended Extensions
+
+Configure in `.vscode/extensions.json` (choose based on the needs):
+
+```json
+{
+  "recommendations": [
+    "dbaeumer.vscode-eslint",
+    "antfu.pnpm-catalog-lens",
+    "antfu.iconify",
+    "antfu.unocss",
+    "antfu.slidev",
+    "vue.volar"
+  ]
+}
+```
+
+## Extension Details
+
+| Extension | Description |
+|-----------|-------------|
+| `dbaeumer.vscode-eslint` | ESLint integration for linting and formatting |
+| `antfu.pnpm-catalog-lens` | Shows pnpm catalog version hints inline |
+| `antfu.iconify` | Iconify icon preview and autocomplete |
+| `antfu.unocss` | UnoCSS IntelliSense and syntax highlighting |
+| `antfu.slidev` | Slidev preview and syntax highlighting for presentations |
+| `vue.volar` | Vue Language Features (official Vue extension) |

.agents/skills/pinia/GENERATION.md

@@ -0,0 +1,5 @@
+# Generation Info
+
+- **Source:** `sources/pinia`
+- **Git SHA:** `55dbfc5c20d4461748996aa74d8c0913e89fb98e`
+- **Generated:** 2026-01-28

.agents/skills/pinia/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: pinia
+description: Pinia official Vue state management library, type-safe and extensible. Use when defining stores, working with state/getters/actions, or implementing store patterns in Vue apps.
+metadata:
+  author: Anthony Fu
+  version: "2026.1.28"
+  source: Generated from https://github.com/vuejs/pinia, scripts located at https://github.com/antfu/skills
+---
+
+# Pinia
+
+Pinia is the official state management library for Vue, designed to be intuitive and type-safe. It supports both Options API and Composition API styles, with first-class TypeScript support and devtools integration.
+
+> The skill is based on Pinia v3.0.4, generated at 2026-01-28.
+
+## Core References
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Stores | Defining stores, state, getters, actions, storeToRefs, subscriptions | [core-stores](references/core-stores.md) |
+
+## Features
+
+### Extensibility
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Plugins | Extend stores with custom properties, state, and behavior | [features-plugins](references/features-plugins.md) |
+
+### Composability
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Composables | Using Vue composables within stores (VueUse, etc.) | [features-composables](references/features-composables.md) |
+| Composing Stores | Store-to-store communication, avoiding circular dependencies | [features-composing-stores](references/features-composing-stores.md) |
+
+## Best Practices
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Testing | Unit testing with @pinia/testing, mocking, stubbing | [best-practices-testing](references/best-practices-testing.md) |
+| Outside Components | Using stores in navigation guards, plugins, middlewares | [best-practices-outside-component](references/best-practices-outside-component.md) |
+
+## Advanced
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| SSR | Server-side rendering, state hydration | [advanced-ssr](references/advanced-ssr.md) |
+| Nuxt | Nuxt integration, auto-imports, SSR best practices | [advanced-nuxt](references/advanced-nuxt.md) |
+| HMR | Hot module replacement for development | [advanced-hmr](references/advanced-hmr.md) |
+
+## Key Recommendations
+
+- **Prefer Setup Stores** for complex logic, composables, and watchers
+- **Use `storeToRefs()`** when destructuring state/getters to preserve reactivity
+- **Actions can be destructured directly** - they're bound to the store
+- **Call stores inside functions** not at module scope, especially for SSR
+- **Add HMR support** to each store for better development experience
+- **Use `@pinia/testing`** for component tests with mocked stores

.agents/skills/pinia/references/advanced-hmr.md

@@ -0,0 +1,61 @@
+---
+name: hot-module-replacement
+description: Enable HMR to preserve store state during development
+---
+
+# Hot Module Replacement (HMR)
+
+Pinia supports HMR to edit stores without page reload, preserving existing state.
+
+## Setup
+
+Add this snippet after each store definition:
+
+```ts
+import { defineStore, acceptHMRUpdate } from 'pinia'
+
+export const useAuth = defineStore('auth', {
+  // store options...
+})
+
+if (import.meta.hot) {
+  import.meta.hot.accept(acceptHMRUpdate(useAuth, import.meta.hot))
+}
+```
+
+## Setup Store Example
+
+```ts
+import { defineStore, acceptHMRUpdate } from 'pinia'
+
+export const useCounterStore = defineStore('counter', () => {
+  const count = ref(0)
+  const increment = () => count.value++
+  return { count, increment }
+})
+
+if (import.meta.hot) {
+  import.meta.hot.accept(acceptHMRUpdate(useCounterStore, import.meta.hot))
+}
+```
+
+## Bundler Support
+
+- **Vite:** Officially supported via `import.meta.hot`
+- **Webpack:** Uses `import.meta.webpackHot`
+- Any bundler implementing the `import.meta.hot` spec should work
+
+## Nuxt
+
+With `@pinia/nuxt`, `acceptHMRUpdate` is auto-imported but you still need to add the HMR snippet manually.
+
+## Benefits
+
+- Edit store logic without losing state
+- Add/remove state, actions, and getters on the fly
+- Faster development iteration
+
+<!--
+Source references:
+- https://pinia.vuejs.org/cookbook/hot-module-replacement.html
+-->

.agents/skills/pinia/references/advanced-nuxt.md

@@ -0,0 +1,119 @@
+---
+name: nuxt-integration
+description: Using Pinia with Nuxt - auto-imports, SSR, and best practices
+---
+
+# Nuxt Integration
+
+Pinia works seamlessly with Nuxt 3/4, handling SSR, serialization, and XSS protection automatically.
+
+## Installation
+
+```bash
+npx nuxi@latest module add pinia
+```
+
+This installs both `@pinia/nuxt` and `pinia`. If `pinia` isn't installed, add it manually.
+
+> **npm users:** If you get `ERESOLVE unable to resolve dependency tree`, add to `package.json`:
+> ```json
+> "overrides": { "vue": "latest" }
+> ```
+
+## Configuration
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@pinia/nuxt'],
+})
+```
+
+## Auto Imports
+
+These are automatically available:
+- `usePinia()` - get pinia instance
+- `defineStore()` - define stores
+- `storeToRefs()` - extract reactive refs
+- `acceptHMRUpdate()` - HMR support
+
+**All stores in `app/stores/` (Nuxt 4) or `stores/` are auto-imported.**
+
+### Custom Store Directories
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@pinia/nuxt'],
+  pinia: {
+    storesDirs: ['./stores/**', './custom-folder/stores/**'],
+  },
+})
+```
+
+## Fetching Data in Pages
+
+Use `callOnce()` for SSR-friendly data fetching:
+
+```vue
+<script setup>
+const store = useStore()
+
+// Run once, data persists across navigations
+await callOnce('user', () => store.fetchUser())
+</script>
+```
+
+### Refetch on Navigation
+
+```vue
+<script setup>
+const store = useStore()
+
+// Refetch on every navigation (like useFetch)
+await callOnce('user', () => store.fetchUser(), { mode: 'navigation' })
+</script>
+```
+
+## Using Stores Outside Components
+
+In navigation guards, middlewares, or other stores, pass the `pinia` instance:
+
+```ts
+// middleware/auth.ts
+export default defineNuxtRouteMiddleware((to) => {
+  const nuxtApp = useNuxtApp()
+  const store = useStore(nuxtApp.$pinia)
+
+  if (to.meta.requiresAuth && !store.isLoggedIn) {
+    return navigateTo('/login')
+  }
+})
+```
+
+Most of the time, you don't need this - just use stores in components or other injection-aware contexts.
+
+## Pinia Plugins with Nuxt
+
+Create a Nuxt plugin:
+
+```ts
+// plugins/myPiniaPlugin.ts
+import { PiniaPluginContext } from 'pinia'
+
+function MyPiniaPlugin({ store }: PiniaPluginContext) {
+  store.$subscribe((mutation) => {
+    console.log(`[🍍 ${mutation.storeId}]: ${mutation.type}`)
+  })
+  return { creationTime: new Date() }
+}
+
+export default defineNuxtPlugin(({ $pinia }) => {
+  $pinia.use(MyPiniaPlugin)
+})
+```
+
+<!--
+Source references:
+- https://pinia.vuejs.org/ssr/nuxt.html
+-->

.agents/skills/pinia/references/advanced-ssr.md

@@ -0,0 +1,121 @@
+---
+name: server-side-rendering
+description: SSR setup, state hydration, and avoiding cross-request state pollution
+---
+
+# Server Side Rendering (SSR)
+
+Pinia works with SSR when stores are called at the top of `setup`, getters, or actions.
+
+> **Using Nuxt?** See the [Nuxt integration](advanced-nuxt.md) instead.
+
+## Basic Usage
+
+```vue
+<script setup>
+// ✅ Works - pinia knows the app context in setup
+const main = useMainStore()
+</script>
+```
+
+## Using Store Outside setup()
+
+Pass the `pinia` instance explicitly:
+
+```ts
+const pinia = createPinia()
+const app = createApp(App)
+app.use(router)
+app.use(pinia)
+
+router.beforeEach((to) => {
+  // ✅ Pass pinia for correct SSR context
+  const main = useMainStore(pinia)
+
+  if (to.meta.requiresAuth && !main.isLoggedIn) {
+    return '/login'
+  }
+})
+```
+
+## serverPrefetch()
+
+Access pinia via `this.$pinia`:
+
+```ts
+export default {
+  serverPrefetch() {
+    const store = useStore(this.$pinia)
+    return store.fetchData()
+  },
+}
+```
+
+## onServerPrefetch()
+
+Works normally:
+
+```vue
+<script setup>
+const store = useStore()
+
+onServerPrefetch(async () => {
+  await store.fetchData()
+})
+</script>
+```
+
+## State Hydration
+
+Serialize state on server and hydrate on client.
+
+### Server Side
+
+Use [devalue](https://github.com/Rich-Harris/devalue) for XSS-safe serialization:
+
+```ts
+import devalue from 'devalue'
+import { createPinia } from 'pinia'
+
+const pinia = createPinia()
+const app = createApp(App)
+app.use(router)
+app.use(pinia)
+
+// After rendering, state is available
+const serializedState = devalue(pinia.state.value)
+// Inject into HTML as global variable
+```
+
+### Client Side
+
+Hydrate before any `useStore()` call:
+
+```ts
+const pinia = createPinia()
+const app = createApp(App)
+app.use(pinia)
+
+// Hydrate from serialized state (e.g., from window.__pinia)
+if (typeof window !== 'undefined') {
+  pinia.state.value = JSON.parse(window.__pinia)
+}
+```
+
+## SSR Examples
+
+- [Vitesse template](https://github.com/antfu/vitesse/blob/main/src/modules/pinia.ts)
+- [vite-plugin-ssr](https://vite-plugin-ssr.com/pinia)
+
+## Key Points
+
+1. Call stores inside functions, not at module scope
+2. Pass `pinia` instance when using stores outside components in SSR
+3. Hydrate state before calling any `useStore()`
+4. Use `devalue` or similar for safe serialization
+5. Avoid cross-request state pollution by creating fresh pinia per request
+
+<!--
+Source references:
+- https://pinia.vuejs.org/ssr/
+-->

.agents/skills/pinia/references/best-practices-outside-component.md

@@ -0,0 +1,115 @@
+---
+name: using-stores-outside-components
+description: Correctly using stores in navigation guards, plugins, and other non-component contexts
+---
+
+# Using Stores Outside Components
+
+Stores need the `pinia` instance, which is automatically injected in components. Outside components, you may need to provide it manually.
+
+## Single Page Applications
+
+Call stores **after** pinia is installed:
+
+```ts
+import { useUserStore } from '@/stores/user'
+import { createPinia } from 'pinia'
+import { createApp } from 'vue'
+import App from './App.vue'
+
+// ❌ Fails - pinia not created yet
+const userStore = useUserStore()
+
+const pinia = createPinia()
+const app = createApp(App)
+app.use(pinia)
+
+// ✅ Works - pinia is active
+const userStore = useUserStore()
+```
+
+## Navigation Guards
+
+**Wrong:** Call at module level
+
+```ts
+import { createRouter } from 'vue-router'
+const router = createRouter({ /* ... */ })
+
+// ❌ May fail depending on import order
+const store = useUserStore()
+
+router.beforeEach((to) => {
+  if (store.isLoggedIn) { /* ... */ }
+})
+```
+
+**Correct:** Call inside the guard
+
+```ts
+router.beforeEach((to) => {
+  // ✅ Called after pinia is installed
+  const store = useUserStore()
+
+  if (to.meta.requiresAuth && !store.isLoggedIn) {
+    return '/login'
+  }
+})
+```
+
+## SSR Applications
+
+Always pass the `pinia` instance to `useStore()`:
+
+```ts
+const pinia = createPinia()
+const app = createApp(App)
+app.use(router)
+app.use(pinia)
+
+router.beforeEach((to) => {
+  // ✅ Pass pinia instance
+  const main = useMainStore(pinia)
+
+  if (to.meta.requiresAuth && !main.isLoggedIn) {
+    return '/login'
+  }
+})
+```
+
+## serverPrefetch()
+
+Access pinia via `this.$pinia`:
+
+```ts
+export default {
+  serverPrefetch() {
+    const store = useStore(this.$pinia)
+    return store.fetchData()
+  },
+}
+```
+
+## onServerPrefetch()
+
+Works normally in `<script setup>`:
+
+```vue
+<script setup>
+const store = useStore()
+
+onServerPrefetch(async () => {
+  // ✅ Just works
+  await store.fetchData()
+})
+</script>
+```
+
+## Key Takeaway
+
+Defer `useStore()` calls to functions that run after pinia is installed, rather than calling at module scope.
+
+<!--
+Source references:
+- https://pinia.vuejs.org/core-concepts/outside-component-usage.html
+-->

.agents/skills/pinia/references/best-practices-testing.md

@@ -0,0 +1,212 @@
+---
+name: testing
+description: Unit testing stores and components with @pinia/testing
+---
+
+# Testing Stores
+
+## Unit Testing Stores
+
+Create a fresh pinia instance for each test:
+
+```ts
+import { setActivePinia, createPinia } from 'pinia'
+import { useCounterStore } from '../src/stores/counter'
+
+describe('Counter Store', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+  })
+
+  it('increments', () => {
+    const counter = useCounterStore()
+    expect(counter.n).toBe(0)
+    counter.increment()
+    expect(counter.n).toBe(1)
+  })
+})
+```
+
+### With Plugins
+
+```ts
+import { setActivePinia, createPinia } from 'pinia'
+import { createApp } from 'vue'
+import { somePlugin } from '../src/stores/plugin'
+
+const app = createApp({})
+
+beforeEach(() => {
+  const pinia = createPinia().use(somePlugin)
+  app.use(pinia)
+  setActivePinia(pinia)
+})
+```
+
+## Testing Components
+
+Install `@pinia/testing`:
+
+```bash
+npm i -D @pinia/testing
+```
+
+Use `createTestingPinia()`:
+
+```ts
+import { mount } from '@vue/test-utils'
+import { createTestingPinia } from '@pinia/testing'
+import { useSomeStore } from '@/stores/myStore'
+
+const wrapper = mount(Counter, {
+  global: {
+    plugins: [createTestingPinia()],
+  },
+})
+
+const store = useSomeStore()
+
+// Manipulate state directly
+store.name = 'new name'
+store.$patch({ name: 'new name' })
+
+// Actions are stubbed by default
+store.someAction()
+expect(store.someAction).toHaveBeenCalledTimes(1)
+```
+
+## Initial State
+
+Set initial state for tests:
+
+```ts
+const wrapper = mount(Counter, {
+  global: {
+    plugins: [
+      createTestingPinia({
+        initialState: {
+          counter: { n: 20 }, // Store name → initial state
+        },
+      }),
+    ],
+  },
+})
+```
+
+## Action Stubbing
+
+### Execute Real Actions
+
+```ts
+createTestingPinia({ stubActions: false })
+```
+
+### Selective Stubbing
+
+```ts
+// Only stub specific actions
+createTestingPinia({
+  stubActions: ['increment', 'reset'],
+})
+
+// Or use a function
+createTestingPinia({
+  stubActions: (actionName, store) => {
+    if (actionName.startsWith('set')) return true
+    return false
+  },
+})
+```
+
+### Mock Action Return Values
+
+```ts
+import type { Mock } from 'vitest'
+
+// After getting store
+store.someAction.mockResolvedValue('mocked value')
+```
+
+## Mocking Getters
+
+Getters are writable in tests:
+
+```ts
+const pinia = createTestingPinia()
+const counter = useCounterStore(pinia)
+
+counter.double = 3 // Override computed value
+
+// Reset to default behavior
+counter.double = undefined
+counter.double // Now computed normally
+```
+
+## Custom Spy Function
+
+If not using Jest/Vitest with globals:
+
+```ts
+import { vi } from 'vitest'
+
+createTestingPinia({
+  createSpy: vi.fn,
+})
+```
+
+With Sinon:
+
+```ts
+import sinon from 'sinon'
+
+createTestingPinia({
+  createSpy: sinon.spy,
+})
+```
+
+## Pinia Plugins in Tests
+
+Pass plugins to `createTestingPinia()`:
+
+```ts
+import { somePlugin } from '../src/stores/plugin'
+
+createTestingPinia({
+  stubActions: false,
+  plugins: [somePlugin],
+})
+```
+
+**Don't use** `testingPinia.use(MyPlugin)` - pass plugins in options.
+
+## Type-Safe Mocked Store
+
+```ts
+import type { Mock } from 'vitest'
+import type { Store, StoreDefinition } from 'pinia'
+
+function mockedStore<TStoreDef extends () => unknown>(
+  useStore: TStoreDef
+): TStoreDef extends StoreDefinition<infer Id, infer State, infer Getters, infer Actions>
+  ? Store<Id, State, Record<string, never>, {
+      [K in keyof Actions]: Actions[K] extends (...args: any[]) => any
+        ? Mock<Actions[K]>
+        : Actions[K]
+    }>
+  : ReturnType<TStoreDef> {
+  return useStore() as any
+}
+
+// Usage
+const store = mockedStore(useSomeStore)
+store.someAction.mockResolvedValue('value') // Typed!
+```
+
+## E2E Tests
+
+No special handling needed - Pinia works normally.
+
+<!--
+Source references:
+- https://pinia.vuejs.org/cookbook/testing.html
+-->

.agents/skills/pinia/references/core-stores.md

@@ -0,0 +1,389 @@
+---
+name: stores
+description: Defining stores, state, getters, and actions in Pinia
+---
+
+# Pinia Stores
+
+Stores are defined using `defineStore()` with a unique name. Each store has three core concepts: **state**, **getters**, and **actions**.
+
+## Defining Stores
+
+### Option Stores
+
+Similar to Vue's Options API:
+
+```ts
+import { defineStore } from 'pinia'
+
+export const useCounterStore = defineStore('counter', {
+  state: () => ({
+    count: 0,
+    name: 'Eduardo',
+  }),
+  getters: {
+    doubleCount: (state) => state.count * 2,
+  },
+  actions: {
+    increment() {
+      this.count++
+    },
+  },
+})
+```
+
+Think of `state` as `data`, `getters` as `computed`, and `actions` as `methods`.
+
+### Setup Stores (Recommended)
+
+Uses Composition API syntax - more flexible and powerful:
+
+```ts
+import { ref, computed } from 'vue'
+import { defineStore } from 'pinia'
+
+export const useCounterStore = defineStore('counter', () => {
+  const count = ref(0)
+  const name = ref('Eduardo')
+  const doubleCount = computed(() => count.value * 2)
+
+  function increment() {
+    count.value++
+  }
+
+  return { count, name, doubleCount, increment }
+})
+```
+
+In Setup Stores: `ref()` → state, `computed()` → getters, `function()` → actions.
+
+**Important:** You must return all state properties for Pinia to track them.
+
+### Using Stores
+
+```vue
+<script setup>
+import { useCounterStore } from '@/stores/counter'
+
+const store = useCounterStore()
+// Access: store.count, store.doubleCount, store.increment()
+</script>
+```
+
+### Destructuring with storeToRefs
+
+```vue
+<script setup>
+import { storeToRefs } from 'pinia'
+import { useCounterStore } from '@/stores/counter'
+
+const store = useCounterStore()
+
+// ❌ Breaks reactivity
+const { name, doubleCount } = store
+
+// ✅ Preserves reactivity for state/getters
+const { name, doubleCount } = storeToRefs(store)
+
+// ✅ Actions can be destructured directly
+const { increment } = store
+</script>
+```
+
+---
+
+## State
+
+State is defined as a function returning the initial state.
+
+### TypeScript
+
+Type inference works automatically. For complex types:
+
+```ts
+interface UserInfo {
+  name: string
+  age: number
+}
+
+export const useUserStore = defineStore('user', {
+  state: () => ({
+    userList: [] as UserInfo[],
+    user: null as UserInfo | null,
+  }),
+})
+```
+
+Or use an interface for the return type:
+
+```ts
+interface State {
+  userList: UserInfo[]
+  user: UserInfo | null
+}
+
+export const useUserStore = defineStore('user', {
+  state: (): State => ({
+    userList: [],
+    user: null,
+  }),
+})
+```
+
+### Accessing and Modifying
+
+```ts
+const store = useStore()
+store.count++
+```
+
+```vue
+<input v-model="store.count" type="number" />
+```
+
+### Mutating with $patch
+
+Apply multiple changes at once:
+
+```ts
+// Object syntax
+store.$patch({
+  count: store.count + 1,
+  name: 'DIO',
+})
+
+// Function syntax (for complex mutations)
+store.$patch((state) => {
+  state.items.push({ name: 'shoes', quantity: 1 })
+  state.hasChanged = true
+})
+```
+
+### Resetting State
+
+Option Stores have built-in `$reset()`. For Setup Stores, implement your own:
+
+```ts
+export const useCounterStore = defineStore('counter', () => {
+  const count = ref(0)
+
+  function $reset() {
+    count.value = 0
+  }
+
+  return { count, $reset }
+})
+```
+
+### Subscribing to State Changes
+
+```ts
+cartStore.$subscribe((mutation, state) => {
+  mutation.type // 'direct' | 'patch object' | 'patch function'
+  mutation.storeId // 'cart'
+  mutation.payload // patch object (only for 'patch object')
+
+  localStorage.setItem('cart', JSON.stringify(state))
+})
+
+// Options
+cartStore.$subscribe(callback, { flush: 'sync' }) // Immediate
+cartStore.$subscribe(callback, { detached: true }) // Keep after unmount
+```
+
+---
+
+## Getters
+
+Getters are computed values, equivalent to Vue's `computed()`.
+
+### Basic Getters
+
+```ts
+getters: {
+  doubleCount: (state) => state.count * 2,
+}
+```
+
+### Accessing Other Getters
+
+Use `this` with explicit return type:
+
+```ts
+getters: {
+  doubleCount: (state) => state.count * 2,
+  doublePlusOne(): number {
+    return this.doubleCount + 1
+  },
+},
+```
+
+### Getters with Arguments
+
+Return a function (note: loses caching):
+
+```ts
+getters: {
+  getUserById: (state) => {
+    return (userId: string) => state.users.find((user) => user.id === userId)
+  },
+},
+```
+
+Cache within parameterized getters:
+
+```ts
+getters: {
+  getActiveUserById(state) {
+    const activeUsers = state.users.filter((user) => user.active)
+    return (userId: string) => activeUsers.find((user) => user.id === userId)
+  },
+},
+```
+
+### Accessing Other Stores in Getters
+
+```ts
+import { useOtherStore } from './other-store'
+
+getters: {
+  combined(state) {
+    const otherStore = useOtherStore()
+    return state.localData + otherStore.data
+  },
+},
+```
+
+---
+
+## Actions
+
+Actions are methods for business logic. Unlike getters, they can be asynchronous.
+
+### Defining Actions
+
+```ts
+actions: {
+  increment() {
+    this.count++
+  },
+  randomizeCounter() {
+    this.count = Math.round(100 * Math.random())
+  },
+},
+```
+
+### Async Actions
+
+```ts
+actions: {
+  async registerUser(login: string, password: string) {
+    try {
+      this.userData = await api.post({ login, password })
+    } catch (error) {
+      return error
+    }
+  },
+},
+```
+
+### Accessing Other Stores in Actions
+
+```ts
+import { useAuthStore } from './auth-store'
+
+actions: {
+  async fetchUserPreferences() {
+    const auth = useAuthStore()
+    if (auth.isAuthenticated) {
+      this.preferences = await fetchPreferences()
+    }
+  },
+},
+```
+
+**SSR:** Call all `useStore()` before any `await`:
+
+```ts
+async orderCart() {
+  // ✅ Call stores before await
+  const user = useUserStore()
+
+  await apiOrderCart(user.token, this.items)
+  // ❌ Don't call useStore() after await in SSR
+}
+```
+
+### Subscribing to Actions
+
+```ts
+const unsubscribe = someStore.$onAction(
+  ({ name, store, args, after, onError }) => {
+    const startTime = Date.now()
+    console.log(`Start "${name}" with params [${args.join(', ')}]`)
+
+    after((result) => {
+      console.log(`Finished "${name}" after ${Date.now() - startTime}ms`)
+    })
+
+    onError((error) => {
+      console.warn(`Failed "${name}": ${error}`)
+    })
+  }
+)
+
+unsubscribe() // Cleanup
+```
+
+Keep subscription after component unmount:
+
+```ts
+someStore.$onAction(callback, true)
+```
+
+---
+
+## Options API Helpers
+
+```ts
+import { mapState, mapWritableState, mapActions } from 'pinia'
+import { useCounterStore } from '../stores/counter'
+
+export default {
+  computed: {
+    // Readonly state/getters
+    ...mapState(useCounterStore, ['count', 'doubleCount']),
+    // Writable state
+    ...mapWritableState(useCounterStore, ['count']),
+  },
+  methods: {
+    ...mapActions(useCounterStore, ['increment']),
+  },
+}
+```
+
+---
+
+## Accessing Global Providers in Setup Stores
+
+```ts
+import { inject } from 'vue'
+import { useRoute } from 'vue-router'
+import { defineStore } from 'pinia'
+
+export const useSearchFilters = defineStore('search-filters', () => {
+  const route = useRoute()
+  const appProvided = inject('appProvided')
+
+  // Don't return these - access them directly in components
+  return { /* ... */ }
+})
+```
+
+<!--
+Source references:
+- https://pinia.vuejs.org/core-concepts/
+- https://pinia.vuejs.org/core-concepts/state.html
+- https://pinia.vuejs.org/core-concepts/getters.html
+- https://pinia.vuejs.org/core-concepts/actions.html
+-->

.agents/skills/pinia/references/features-composables.md

@@ -0,0 +1,114 @@
+---
+name: composables-in-stores
+description: Using Vue composables within Pinia stores
+---
+
+# Composables in Stores
+
+Pinia stores can leverage Vue composables for reusable stateful logic.
+
+## Option Stores
+
+Call composables inside the `state` property, but only those returning writable refs:
+
+```ts
+import { defineStore } from 'pinia'
+import { useLocalStorage } from '@vueuse/core'
+
+export const useAuthStore = defineStore('auth', {
+  state: () => ({
+    user: useLocalStorage('pinia/auth/login', 'bob'),
+  }),
+})
+```
+
+**Works:** Composables returning `ref()`:
+- `useLocalStorage`
+- `useAsyncState`
+
+**Doesn't work in Option Stores:**
+- Composables exposing functions
+- Composables exposing readonly data
+
+## Setup Stores
+
+More flexible - can use almost any composable:
+
+```ts
+import { defineStore } from 'pinia'
+import { useMediaControls } from '@vueuse/core'
+import { ref } from 'vue'
+
+export const useVideoPlayer = defineStore('video', () => {
+  const videoElement = ref<HTMLVideoElement>()
+  const src = ref('/data/video.mp4')
+  const { playing, volume, currentTime, togglePictureInPicture } =
+    useMediaControls(videoElement, { src })
+
+  function loadVideo(element: HTMLVideoElement, newSrc: string) {
+    videoElement.value = element
+    src.value = newSrc
+  }
+
+  return {
+    src,
+    playing,
+    volume,
+    currentTime,
+    loadVideo,
+    togglePictureInPicture,
+  }
+})
+```
+
+**Note:** Don't return non-serializable DOM refs like `videoElement` - they're internal implementation details.
+
+## SSR Considerations
+
+### Option Stores with hydrate()
+
+Define a `hydrate()` function to handle client-side hydration:
+
+```ts
+import { defineStore } from 'pinia'
+import { useLocalStorage } from '@vueuse/core'
+
+export const useAuthStore = defineStore('auth', {
+  state: () => ({
+    user: useLocalStorage('pinia/auth/login', 'bob'),
+  }),
+
+  hydrate(state, initialState) {
+    // Ignore server state, read from browser
+    state.user = useLocalStorage('pinia/auth/login', 'bob')
+  },
+})
+```
+
+### Setup Stores with skipHydrate()
+
+Mark state that shouldn't hydrate from server:
+
+```ts
+import { defineStore, skipHydrate } from 'pinia'
+import { useEyeDropper, useLocalStorage } from '@vueuse/core'
+
+export const useColorStore = defineStore('colors', () => {
+  const { isSupported, open, sRGBHex } = useEyeDropper()
+  const lastColor = useLocalStorage('lastColor', sRGBHex)
+
+  return {
+    // Skip hydration for client-only state
+    lastColor: skipHydrate(lastColor),
+    open,       // Function - no hydration needed
+    isSupported, // Boolean - not reactive
+  }
+})
+```
+
+`skipHydrate()` only applies to state properties (refs), not functions or non-reactive values.
+
+<!--
+Source references:
+- https://pinia.vuejs.org/cookbook/composables.html
+-->

.agents/skills/pinia/references/features-composing-stores.md

@@ -0,0 +1,134 @@
+---
+name: composing-stores
+description: Store-to-store communication and avoiding circular dependencies
+---
+
+# Composing Stores
+
+Stores can use each other for shared state and logic.
+
+## Rule: Avoid Circular Dependencies
+
+Two stores cannot directly read each other's state during setup:
+
+```ts
+// ❌ Infinite loop
+const useX = defineStore('x', () => {
+  const y = useY()
+  y.name // Don't read here!
+  return { name: ref('X') }
+})
+
+const useY = defineStore('y', () => {
+  const x = useX()
+  x.name // Don't read here!
+  return { name: ref('Y') }
+})
+```
+
+**Solution:** Read in getters, computed, or actions:
+
+```ts
+const useX = defineStore('x', () => {
+  const y = useY()
+
+  // ✅ Read in computed/actions
+  function doSomething() {
+    const yName = y.name
+  }
+
+  return { name: ref('X'), doSomething }
+})
+```
+
+## Setup Stores: Use Store at Top
+
+```ts
+import { defineStore } from 'pinia'
+import { useUserStore } from './user'
+
+export const useCartStore = defineStore('cart', () => {
+  const user = useUserStore()
+  const list = ref([])
+
+  const summary = computed(() => {
+    return `Hi ${user.name}, you have ${list.value.length} items`
+  })
+
+  function purchase() {
+    return apiPurchase(user.id, list.value)
+  }
+
+  return { list, summary, purchase }
+})
+```
+
+## Shared Getters
+
+Call `useStore()` inside a getter:
+
+```ts
+import { useUserStore } from './user'
+
+export const useCartStore = defineStore('cart', {
+  getters: {
+    summary(state) {
+      const user = useUserStore()
+      return `Hi ${user.name}, you have ${state.list.length} items`
+    },
+  },
+})
+```
+
+## Shared Actions
+
+Call `useStore()` inside an action:
+
+```ts
+import { useUserStore } from './user'
+import { apiOrderCart } from './api'
+
+export const useCartStore = defineStore('cart', {
+  actions: {
+    async orderCart() {
+      const user = useUserStore()
+
+      try {
+        await apiOrderCart(user.token, this.items)
+        this.emptyCart()
+      } catch (err) {
+        displayError(err)
+      }
+    },
+  },
+})
+```
+
+## SSR: Call Stores Before Await
+
+In async actions, call all stores before any `await`:
+
+```ts
+actions: {
+  async orderCart() {
+    // ✅ All useStore() calls before await
+    const user = useUserStore()
+    const analytics = useAnalyticsStore()
+
+    try {
+      await apiOrderCart(user.token, this.items)
+      // ❌ Don't call useStore() after await (SSR issue)
+      // const otherStore = useOtherStore()
+    } catch (err) {
+      displayError(err)
+    }
+  },
+}
+```
+
+This ensures the correct Pinia instance is used during SSR.
+
+<!--
+Source references:
+- https://pinia.vuejs.org/cookbook/composing-stores.html
+-->

.agents/skills/pinia/references/features-plugins.md

@@ -0,0 +1,203 @@
+---
+name: plugins
+description: Extend stores with custom properties, methods, and behavior
+---
+
+# Plugins
+
+Plugins extend all stores with custom properties, methods, or behavior.
+
+## Basic Plugin
+
+```ts
+import { createPinia } from 'pinia'
+
+function SecretPiniaPlugin() {
+  return { secret: 'the cake is a lie' }
+}
+
+const pinia = createPinia()
+pinia.use(SecretPiniaPlugin)
+
+// In any store
+const store = useStore()
+store.secret // 'the cake is a lie'
+```
+
+## Plugin Context
+
+Plugins receive a context object:
+
+```ts
+import { PiniaPluginContext } from 'pinia'
+
+export function myPiniaPlugin(context: PiniaPluginContext) {
+  context.pinia   // pinia instance
+  context.app     // Vue app instance
+  context.store   // store being augmented
+  context.options // store definition options
+}
+```
+
+## Adding Properties
+
+Return an object to add properties (tracked in devtools):
+
+```ts
+pinia.use(() => ({ hello: 'world' }))
+```
+
+Or set directly on store:
+
+```ts
+pinia.use(({ store }) => {
+  store.hello = 'world'
+  // For devtools visibility in dev mode
+  if (process.env.NODE_ENV === 'development') {
+    store._customProperties.add('hello')
+  }
+})
+```
+
+## Adding State
+
+Add to both `store` and `store.$state` for SSR/devtools:
+
+```ts
+import { toRef, ref } from 'vue'
+
+pinia.use(({ store }) => {
+  if (!store.$state.hasOwnProperty('hasError')) {
+    const hasError = ref(false)
+    store.$state.hasError = hasError
+  }
+  store.hasError = toRef(store.$state, 'hasError')
+})
+```
+
+## Adding External Properties
+
+Wrap non-reactive objects with `markRaw()`:
+
+```ts
+import { markRaw } from 'vue'
+import { router } from './router'
+
+pinia.use(({ store }) => {
+  store.router = markRaw(router)
+})
+```
+
+## Custom Store Options
+
+Define custom options consumed by plugins:
+
+```ts
+// Store definition
+defineStore('search', {
+  actions: {
+    searchContacts() { /* ... */ },
+  },
+  debounce: {
+    searchContacts: 300,
+  },
+})
+
+// Plugin reads custom option
+import debounce from 'lodash/debounce'
+
+pinia.use(({ options, store }) => {
+  if (options.debounce) {
+    return Object.keys(options.debounce).reduce((acc, action) => {
+      acc[action] = debounce(store[action], options.debounce[action])
+      return acc
+    }, {})
+  }
+})
+```
+
+For Setup Stores, pass options as third argument:
+
+```ts
+defineStore(
+  'search',
+  () => { /* ... */ },
+  {
+    debounce: { searchContacts: 300 },
+  }
+)
+```
+
+## TypeScript Augmentation
+
+### Custom Properties
+
+```ts
+import 'pinia'
+import type { Router } from 'vue-router'
+
+declare module 'pinia' {
+  export interface PiniaCustomProperties {
+    router: Router
+    hello: string
+  }
+}
+```
+
+### Custom State
+
+```ts
+declare module 'pinia' {
+  export interface PiniaCustomStateProperties<S> {
+    hasError: boolean
+  }
+}
+```
+
+### Custom Options
+
+```ts
+declare module 'pinia' {
+  export interface DefineStoreOptionsBase<S, Store> {
+    debounce?: Partial<Record<keyof StoreActions<Store>, number>>
+  }
+}
+```
+
+## Subscribe in Plugins
+
+```ts
+pinia.use(({ store }) => {
+  store.$subscribe(() => {
+    // React to state changes
+  })
+  store.$onAction(() => {
+    // React to actions
+  })
+})
+```
+
+## Nuxt Plugin
+
+Create a Nuxt plugin to add Pinia plugins:
+
+```ts
+// plugins/myPiniaPlugin.ts
+import { PiniaPluginContext } from 'pinia'
+
+function MyPiniaPlugin({ store }: PiniaPluginContext) {
+  store.$subscribe((mutation) => {
+    console.log(`[🍍 ${mutation.storeId}]: ${mutation.type}`)
+  })
+  return { creationTime: new Date() }
+}
+
+export default defineNuxtPlugin(({ $pinia }) => {
+  $pinia.use(MyPiniaPlugin)
+})
+```
+
+<!--
+Source references:
+- https://pinia.vuejs.org/core-concepts/plugins.html
+-->

.agents/skills/pnpm/GENERATION.md

@@ -0,0 +1,5 @@
+# Generation Info
+
+- **Source:** `sources/pnpm`
+- **Git SHA:** `a1d6d5aef9d5f369fa2f0d8a54f1edbaff8b23b3`
+- **Generated:** 2026-01-28

.agents/skills/pnpm/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: pnpm
+description: Node.js package manager with strict dependency resolution. Use when running pnpm specific commands, configuring workspaces, or managing dependencies with catalogs, patches, or overrides.
+metadata:
+  author: Anthony Fu
+  version: "2026.1.28"
+  source: Generated from https://github.com/pnpm/pnpm, scripts located at https://github.com/antfu/skills
+---
+
+pnpm is a fast, disk space efficient package manager. It uses a content-addressable store to deduplicate packages across all projects on a machine, saving significant disk space. pnpm enforces strict dependency resolution by default, preventing phantom dependencies. Configuration should preferably be placed in `pnpm-workspace.yaml` for pnpm-specific settings.
+
+**Important:** When working with pnpm projects, agents should check for `pnpm-workspace.yaml` and `.npmrc` files to understand workspace structure and configuration. Always use `--frozen-lockfile` in CI environments.
+
+> The skill is based on pnpm 10.x, generated at 2026-01-28.
+
+## Core
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| CLI Commands | Install, add, remove, update, run, exec, dlx, and workspace commands | [core-cli](references/core-cli.md) |
+| Configuration | pnpm-workspace.yaml, .npmrc settings, and package.json fields | [core-config](references/core-config.md) |
+| Workspaces | Monorepo support with filtering, workspace protocol, and shared lockfile | [core-workspaces](references/core-workspaces.md) |
+| Store | Content-addressable storage, hard links, and disk efficiency | [core-store](references/core-store.md) |
+
+## Features
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Catalogs | Centralized dependency version management for workspaces | [features-catalogs](references/features-catalogs.md) |
+| Overrides | Force specific versions of dependencies including transitive | [features-overrides](references/features-overrides.md) |
+| Patches | Modify third-party packages with custom fixes | [features-patches](references/features-patches.md) |
+| Aliases | Install packages under custom names using npm: protocol | [features-aliases](references/features-aliases.md) |
+| Hooks | Customize resolution with .pnpmfile.cjs hooks | [features-hooks](references/features-hooks.md) |
+| Peer Dependencies | Auto-install, strict mode, and dependency rules | [features-peer-deps](references/features-peer-deps.md) |
+
+## Best Practices
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| CI/CD Setup | GitHub Actions, GitLab CI, Docker, and caching strategies | [best-practices-ci](references/best-practices-ci.md) |
+| Migration | Migrating from npm/Yarn, handling phantom deps, monorepo migration | [best-practices-migration](references/best-practices-migration.md) |
+| Performance | Install optimizations, store caching, workspace parallelization | [best-practices-performance](references/best-practices-performance.md) |

.agents/skills/pnpm/references/best-practices-ci.md

@@ -0,0 +1,285 @@
+---
+name: pnpm-ci-cd-setup
+description: Optimizing pnpm for continuous integration and deployment workflows
+---
+
+# pnpm CI/CD Setup
+
+Best practices for using pnpm in CI/CD environments for fast, reliable builds.
+
+## GitHub Actions
+
+### Basic Setup
+
+```yaml
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+      
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm test
+      - run: pnpm build
+```
+
+### With Store Caching
+
+For larger projects, cache the pnpm store:
+
+```yaml
+- uses: pnpm/action-setup@v4
+  with:
+    version: 9
+
+- name: Get pnpm store directory
+  shell: bash
+  run: |
+    echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+
+- uses: actions/cache@v4
+  name: Setup pnpm cache
+  with:
+    path: ${{ env.STORE_PATH }}
+    key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+    restore-keys: |
+      ${{ runner.os }}-pnpm-store-
+
+- run: pnpm install --frozen-lockfile
+```
+
+### Matrix Testing
+
+```yaml
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        node: [18, 20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm test
+```
+
+## GitLab CI
+
+```yaml
+image: node:20
+
+stages:
+  - install
+  - test
+  - build
+
+variables:
+  PNPM_HOME: /root/.local/share/pnpm
+  PATH: $PNPM_HOME:$PATH
+
+before_script:
+  - corepack enable
+  - corepack prepare pnpm@latest --activate
+
+cache:
+  key: ${CI_COMMIT_REF_SLUG}
+  paths:
+    - .pnpm-store
+
+install:
+  stage: install
+  script:
+    - pnpm config set store-dir .pnpm-store
+    - pnpm install --frozen-lockfile
+
+test:
+  stage: test
+  script:
+    - pnpm test
+
+build:
+  stage: build
+  script:
+    - pnpm build
+```
+
+## Docker
+
+### Multi-Stage Build
+
+```dockerfile
+# Build stage
+FROM node:20-slim AS builder
+
+# Enable corepack for pnpm
+RUN corepack enable
+
+WORKDIR /app
+
+# Copy package files first for layer caching
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY packages/*/package.json ./packages/
+
+# Install dependencies
+RUN pnpm install --frozen-lockfile
+
+# Copy source and build
+COPY . .
+RUN pnpm build
+
+# Production stage
+FROM node:20-slim AS runner
+
+RUN corepack enable
+WORKDIR /app
+
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/package.json ./
+COPY --from=builder /app/pnpm-lock.yaml ./
+
+# Production install
+RUN pnpm install --frozen-lockfile --prod
+
+CMD ["node", "dist/index.js"]
+```
+
+### Optimized for Monorepos
+
+```dockerfile
+FROM node:20-slim AS builder
+RUN corepack enable
+WORKDIR /app
+
+# Copy workspace config
+COPY pnpm-lock.yaml pnpm-workspace.yaml ./
+
+# Copy all package.json files maintaining structure
+COPY packages/core/package.json ./packages/core/
+COPY packages/api/package.json ./packages/api/
+
+# Install all dependencies
+RUN pnpm install --frozen-lockfile
+
+# Copy source
+COPY . .
+
+# Build specific package
+RUN pnpm --filter @myorg/api build
+```
+
+## Key CI Flags
+
+### --frozen-lockfile
+
+**Always use in CI.** Fails if `pnpm-lock.yaml` needs updates:
+
+```bash
+pnpm install --frozen-lockfile
+```
+
+### --prefer-offline
+
+Use cached packages when available:
+
+```bash
+pnpm install --frozen-lockfile --prefer-offline
+```
+
+### --ignore-scripts
+
+Skip lifecycle scripts for faster installs (use cautiously):
+
+```bash
+pnpm install --frozen-lockfile --ignore-scripts
+```
+
+## Corepack Integration
+
+Use Corepack to manage pnpm version:
+
+```json
+// package.json
+{
+  "packageManager": "pnpm@9.0.0"
+}
+```
+
+```yaml
+# GitHub Actions
+- run: corepack enable
+- run: pnpm install --frozen-lockfile
+```
+
+## Monorepo CI Strategies
+
+### Build Changed Packages Only
+
+```yaml
+- name: Build changed packages
+  run: |
+    pnpm --filter "...[origin/main]" build
+```
+
+### Parallel Jobs per Package
+
+```yaml
+jobs:
+  detect-changes:
+    runs-on: ubuntu-latest
+    outputs:
+      packages: ${{ steps.changes.outputs.packages }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - id: changes
+        run: |
+          echo "packages=$(pnpm --filter '...[origin/main]' list --json | jq -c '[.[].name]')" >> $GITHUB_OUTPUT
+
+  test:
+    needs: detect-changes
+    if: needs.detect-changes.outputs.packages != '[]'
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        package: ${{ fromJson(needs.detect-changes.outputs.packages) }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm --filter ${{ matrix.package }} test
+```
+
+## Best Practices Summary
+
+1. **Always use `--frozen-lockfile`** in CI
+2. **Cache the pnpm store** for faster installs
+3. **Use Corepack** for consistent pnpm versions
+4. **Specify `packageManager`** in package.json
+5. **Use `--filter`** in monorepos to build only what changed
+6. **Multi-stage Docker builds** for smaller images
+
+<!-- 
+Source references:
+- https://pnpm.io/continuous-integration
+- https://github.com/pnpm/action-setup
+-->

.agents/skills/pnpm/references/best-practices-migration.md

@@ -0,0 +1,291 @@
+---
+name: migration-to-pnpm
+description: Migrating from npm or Yarn to pnpm with minimal friction
+---
+
+# Migration to pnpm
+
+Guide for migrating existing projects from npm or Yarn to pnpm.
+
+## Quick Migration
+
+### From npm
+
+```bash
+# Remove npm lockfile and node_modules
+rm -rf node_modules package-lock.json
+
+# Install with pnpm
+pnpm install
+```
+
+### From Yarn
+
+```bash
+# Remove yarn lockfile and node_modules
+rm -rf node_modules yarn.lock
+
+# Install with pnpm
+pnpm install
+```
+
+### Import Existing Lockfile
+
+pnpm can import existing lockfiles:
+
+```bash
+# Import from npm or yarn lockfile
+pnpm import
+
+# This creates pnpm-lock.yaml from:
+# - package-lock.json (npm)
+# - yarn.lock (yarn)
+# - npm-shrinkwrap.json (npm)
+```
+
+## Handling Common Issues
+
+### Phantom Dependencies
+
+pnpm is strict about dependencies. If code imports a package not in `package.json`, it will fail.
+
+**Problem:**
+```js
+// Works with npm (hoisted), fails with pnpm
+import lodash from 'lodash' // Not in dependencies, installed by another package
+```
+
+**Solution:** Add missing dependencies explicitly:
+```bash
+pnpm add lodash
+```
+
+### Missing Peer Dependencies
+
+pnpm reports peer dependency issues by default.
+
+**Option 1:** Let pnpm auto-install:
+```ini
+# .npmrc (default in pnpm v8+)
+auto-install-peers=true
+```
+
+**Option 2:** Install manually:
+```bash
+pnpm add react react-dom
+```
+
+**Option 3:** Suppress warnings if acceptable:
+```json
+{
+  "pnpm": {
+    "peerDependencyRules": {
+      "ignoreMissing": ["react"]
+    }
+  }
+}
+```
+
+### Symlink Issues
+
+Some tools don't work with symlinks. Use hoisted mode:
+
+```ini
+# .npmrc
+node-linker=hoisted
+```
+
+Or hoist specific packages:
+
+```ini
+public-hoist-pattern[]=*eslint*
+public-hoist-pattern[]=*babel*
+```
+
+### Native Module Rebuilds
+
+If native modules fail, try:
+
+```bash
+# Rebuild all native modules
+pnpm rebuild
+
+# Or reinstall
+rm -rf node_modules
+pnpm install
+```
+
+## Monorepo Migration
+
+### From npm Workspaces
+
+1. Create `pnpm-workspace.yaml`:
+   ```yaml
+   packages:
+     - 'packages/*'
+   ```
+
+2. Update internal dependencies to use workspace protocol:
+   ```json
+   {
+     "dependencies": {
+       "@myorg/utils": "workspace:^"
+     }
+   }
+   ```
+
+3. Install:
+   ```bash
+   rm -rf node_modules packages/*/node_modules package-lock.json
+   pnpm install
+   ```
+
+### From Yarn Workspaces
+
+1. Remove Yarn-specific files:
+   ```bash
+   rm yarn.lock .yarnrc.yml
+   rm -rf .yarn
+   ```
+
+2. Create `pnpm-workspace.yaml` matching `workspaces` in package.json:
+   ```yaml
+   packages:
+     - 'packages/*'
+   ```
+
+3. Update `package.json` - remove Yarn workspace config if not needed:
+   ```json
+   {
+     // Remove "workspaces" field (optional, pnpm uses pnpm-workspace.yaml)
+   }
+   ```
+
+4. Convert workspace references:
+   ```json
+   // From Yarn
+   "@myorg/utils": "*"
+   
+   // To pnpm
+   "@myorg/utils": "workspace:*"
+   ```
+
+### From Lerna
+
+pnpm can replace Lerna for most use cases:
+
+```bash
+# Lerna: run script in all packages
+lerna run build
+
+# pnpm equivalent
+pnpm -r run build
+
+# Lerna: run in specific package
+lerna run build --scope=@myorg/app
+
+# pnpm equivalent  
+pnpm --filter @myorg/app run build
+
+# Lerna: publish
+lerna publish
+
+# pnpm: use changesets instead
+pnpm add -Dw @changesets/cli
+pnpm changeset
+pnpm changeset version
+pnpm publish -r
+```
+
+## Configuration Migration
+
+### .npmrc Settings
+
+Most npm/Yarn settings work in pnpm's `.npmrc`:
+
+```ini
+# Registry settings (same as npm)
+registry=https://registry.npmjs.org/
+@myorg:registry=https://npm.myorg.com/
+
+# Auth tokens (same as npm)
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}
+
+# pnpm-specific additions
+auto-install-peers=true
+strict-peer-dependencies=false
+```
+
+### Scripts Migration
+
+Most scripts work unchanged. Update pnpm-specific patterns:
+
+```json
+{
+  "scripts": {
+    // npm: recursive scripts
+    "build:all": "npm run build --workspaces",
+    // pnpm: use -r flag
+    "build:all": "pnpm -r run build",
+    
+    // npm: run in specific workspace  
+    "dev:app": "npm run dev -w packages/app",
+    // pnpm: use --filter
+    "dev:app": "pnpm --filter @myorg/app run dev"
+  }
+}
+```
+
+## CI/CD Migration
+
+Update CI configuration:
+
+```yaml
+# Before (npm)
+- run: npm ci
+
+# After (pnpm)
+- uses: pnpm/action-setup@v4
+- run: pnpm install --frozen-lockfile
+```
+
+Add to `package.json` for Corepack:
+```json
+{
+  "packageManager": "pnpm@9.0.0"
+}
+```
+
+## Gradual Migration
+
+For large projects, migrate gradually:
+
+1. **Start with CI**: Use pnpm in CI, keep npm/yarn locally
+2. **Add pnpm-lock.yaml**: Run `pnpm import` to create lockfile
+3. **Test thoroughly**: Ensure builds work with pnpm
+4. **Update documentation**: Update README, CONTRIBUTING
+5. **Remove old files**: Delete old lockfiles after team adoption
+
+## Rollback Plan
+
+If migration causes issues:
+
+```bash
+# Remove pnpm files
+rm -rf node_modules pnpm-lock.yaml pnpm-workspace.yaml
+
+# Restore npm
+npm install
+
+# Or restore Yarn
+yarn install
+```
+
+Keep old lockfile in git history for easy rollback.
+
+<!-- 
+Source references:
+- https://pnpm.io/installation
+- https://pnpm.io/cli/import
+- https://pnpm.io/limitations
+-->

.agents/skills/pnpm/references/best-practices-performance.md

@@ -0,0 +1,284 @@
+---
+name: pnpm-performance-optimization
+description: Tips and tricks for faster installs and better performance
+---
+
+# pnpm Performance Optimization
+
+pnpm is fast by default, but these optimizations can make it even faster.
+
+## Install Optimizations
+
+### Use Frozen Lockfile
+
+Skip resolution when lockfile exists:
+
+```bash
+pnpm install --frozen-lockfile
+```
+
+This is faster because pnpm skips the resolution phase entirely.
+
+### Prefer Offline Mode
+
+Use cached packages when available:
+
+```bash
+pnpm install --prefer-offline
+```
+
+Or configure globally:
+```ini
+# .npmrc
+prefer-offline=true
+```
+
+### Skip Optional Dependencies
+
+If you don't need optional deps:
+
+```bash
+pnpm install --no-optional
+```
+
+### Skip Scripts
+
+For CI or when scripts aren't needed:
+
+```bash
+pnpm install --ignore-scripts
+```
+
+**Caution:** Some packages require postinstall scripts to work correctly.
+
+### Only Build Specific Dependencies
+
+Only run build scripts for specific packages:
+
+```ini
+# .npmrc
+onlyBuiltDependencies[]=esbuild
+onlyBuiltDependencies[]=sharp
+onlyBuiltDependencies[]=@swc/core
+```
+
+Or skip builds entirely for deps that don't need them:
+
+```json
+{
+  "pnpm": {
+    "neverBuiltDependencies": ["fsevents", "cpu-features"]
+  }
+}
+```
+
+## Store Optimizations
+
+### Side Effects Cache
+
+Cache native module build results:
+
+```ini
+# .npmrc
+side-effects-cache=true
+```
+
+This caches the results of postinstall scripts, speeding up subsequent installs.
+
+### Shared Store
+
+Use a single store for all projects (default behavior):
+
+```ini
+# .npmrc
+store-dir=~/.pnpm-store
+```
+
+Benefits:
+- Packages downloaded once for all projects
+- Hard links save disk space
+- Faster installs from cache
+
+### Store Maintenance
+
+Periodically clean unused packages:
+
+```bash
+# Remove unreferenced packages
+pnpm store prune
+
+# Check store integrity
+pnpm store status
+```
+
+## Workspace Optimizations
+
+### Parallel Execution
+
+Run workspace scripts in parallel:
+
+```bash
+pnpm -r --parallel run build
+```
+
+Control concurrency:
+```ini
+# .npmrc
+workspace-concurrency=8
+```
+
+### Stream Output
+
+See output in real-time:
+
+```bash
+pnpm -r --stream run build
+```
+
+### Filter to Changed Packages
+
+Only build what changed:
+
+```bash
+# Build packages changed since main branch
+pnpm --filter "...[origin/main]" run build
+```
+
+### Topological Order
+
+Build dependencies before dependents:
+
+```bash
+pnpm -r run build
+# Automatically runs in topological order
+```
+
+For explicit sequential builds:
+```bash
+pnpm -r --workspace-concurrency=1 run build
+```
+
+## Network Optimizations
+
+### Configure Registry
+
+Use closest/fastest registry:
+
+```ini
+# .npmrc
+registry=https://registry.npmmirror.com/
+```
+
+### HTTP Settings
+
+Tune network settings:
+
+```ini
+# .npmrc
+fetch-retries=3
+fetch-retry-mintimeout=10000
+fetch-retry-maxtimeout=60000
+network-concurrency=16
+```
+
+### Proxy Configuration
+
+```ini
+# .npmrc
+proxy=http://proxy.company.com:8080
+https-proxy=http://proxy.company.com:8080
+```
+
+## Lockfile Optimization
+
+### Single Lockfile (Monorepos)
+
+Use shared lockfile for all packages (default):
+
+```ini
+# .npmrc
+shared-workspace-lockfile=true
+```
+
+Benefits:
+- Single source of truth
+- Faster resolution
+- Consistent versions across workspace
+
+### Lockfile-only Mode
+
+Only update lockfile without installing:
+
+```bash
+pnpm install --lockfile-only
+```
+
+## Benchmarking
+
+### Compare Install Times
+
+```bash
+# Clean install
+rm -rf node_modules pnpm-lock.yaml
+time pnpm install
+
+# Cached install (with lockfile)
+rm -rf node_modules
+time pnpm install --frozen-lockfile
+
+# With store cache
+time pnpm install --frozen-lockfile --prefer-offline
+```
+
+### Profile Resolution
+
+Debug slow installs:
+
+```bash
+# Verbose logging
+pnpm install --reporter=append-only
+
+# Debug mode
+DEBUG=pnpm:* pnpm install
+```
+
+## Configuration Summary
+
+Optimized `.npmrc` for performance:
+
+```ini
+# Install behavior
+prefer-offline=true
+auto-install-peers=true
+
+# Build optimization  
+side-effects-cache=true
+# Only build what's necessary
+onlyBuiltDependencies[]=esbuild
+onlyBuiltDependencies[]=@swc/core
+
+# Network
+fetch-retries=3
+network-concurrency=16
+
+# Workspace
+workspace-concurrency=4
+```
+
+## Quick Reference
+
+| Scenario | Command/Setting |
+|----------|-----------------|
+| CI installs | `pnpm install --frozen-lockfile` |
+| Offline development | `--prefer-offline` |
+| Skip native builds | `neverBuiltDependencies` |
+| Parallel workspace | `pnpm -r --parallel run build` |
+| Build changed only | `pnpm --filter "...[origin/main]" build` |
+| Clean store | `pnpm store prune` |
+
+<!-- 
+Source references:
+- https://pnpm.io/npmrc
+- https://pnpm.io/cli/install
+- https://pnpm.io/filtering
+-->

.agents/skills/pnpm/references/core-cli.md

@@ -0,0 +1,229 @@
+---
+name: pnpm-cli-commands
+description: Essential pnpm commands for package management, running scripts, and workspace operations
+---
+
+# pnpm CLI Commands
+
+pnpm provides a comprehensive CLI for package management with commands similar to npm/yarn but with unique features.
+
+## Installation Commands
+
+### Install all dependencies
+```bash
+pnpm install
+# or
+pnpm i
+```
+
+### Add a dependency
+```bash
+# Production dependency
+pnpm add <pkg>
+
+# Dev dependency
+pnpm add -D <pkg>
+pnpm add --save-dev <pkg>
+
+# Optional dependency
+pnpm add -O <pkg>
+
+# Global package
+pnpm add -g <pkg>
+
+# Specific version
+pnpm add <pkg>@<version>
+pnpm add <pkg>@next
+pnpm add <pkg>@^1.0.0
+```
+
+### Remove a dependency
+```bash
+pnpm remove <pkg>
+pnpm rm <pkg>
+pnpm uninstall <pkg>
+pnpm un <pkg>
+```
+
+### Update dependencies
+```bash
+# Update all
+pnpm update
+pnpm up
+
+# Update specific package
+pnpm update <pkg>
+
+# Update to latest (ignore semver)
+pnpm update --latest
+pnpm up -L
+
+# Interactive update
+pnpm update --interactive
+pnpm up -i
+```
+
+## Script Commands
+
+### Run scripts
+```bash
+pnpm run <script>
+# or shorthand
+pnpm <script>
+
+# Pass arguments to script
+pnpm run build -- --watch
+
+# Run script if exists (no error if missing)
+pnpm run --if-present build
+```
+
+### Execute binaries
+```bash
+# Run local binary
+pnpm exec <command>
+
+# Example
+pnpm exec eslint .
+```
+
+### dlx - Run without installing
+```bash
+# Like npx but for pnpm
+pnpm dlx <pkg>
+
+# Examples
+pnpm dlx create-vite my-app
+pnpm dlx degit user/repo my-project
+```
+
+## Workspace Commands
+
+### Run in all packages
+```bash
+# Run script in all workspace packages
+pnpm -r run <script>
+pnpm --recursive run <script>
+
+# Run in specific packages
+pnpm --filter <pattern> run <script>
+
+# Examples
+pnpm --filter "./packages/**" run build
+pnpm --filter "!./packages/internal/**" run test
+pnpm --filter "@myorg/*" run lint
+```
+
+### Filter patterns
+```bash
+# By package name
+pnpm --filter <pkg-name> <command>
+pnpm --filter "@scope/pkg" build
+
+# By directory
+pnpm --filter "./packages/core" test
+
+# Dependencies of a package
+pnpm --filter "...@scope/app" build
+
+# Dependents of a package
+pnpm --filter "@scope/core..." test
+
+# Changed packages since commit/branch
+pnpm --filter "...[origin/main]" build
+```
+
+## Other Useful Commands
+
+### Link packages
+```bash
+# Link global package
+pnpm link --global
+pnpm link -g
+
+# Use linked package
+pnpm link --global <pkg>
+```
+
+### Patch packages
+```bash
+# Create patch for a package
+pnpm patch <pkg>@<version>
+
+# After editing, commit the patch
+pnpm patch-commit <path>
+
+# Remove a patch
+pnpm patch-remove <pkg>
+```
+
+### Store management
+```bash
+# Show store path
+pnpm store path
+
+# Remove unreferenced packages
+pnpm store prune
+
+# Check store integrity
+pnpm store status
+```
+
+### Other commands
+```bash
+# Clean install (like npm ci)
+pnpm install --frozen-lockfile
+
+# List installed packages
+pnpm list
+pnpm ls
+
+# Why is package installed?
+pnpm why <pkg>
+
+# Outdated packages
+pnpm outdated
+
+# Audit for vulnerabilities
+pnpm audit
+
+# Rebuild native modules
+pnpm rebuild
+
+# Import from npm/yarn lockfile
+pnpm import
+
+# Create tarball
+pnpm pack
+
+# Publish package
+pnpm publish
+```
+
+## Useful Flags
+
+```bash
+# Ignore scripts
+pnpm install --ignore-scripts
+
+# Prefer offline (use cache)
+pnpm install --prefer-offline
+
+# Strict peer dependencies
+pnpm install --strict-peer-dependencies
+
+# Production only
+pnpm install --prod
+pnpm install -P
+
+# No optional dependencies
+pnpm install --no-optional
+```
+
+<!-- 
+Source references:
+- https://pnpm.io/cli/install
+- https://pnpm.io/cli/add
+- https://pnpm.io/cli/run
+- https://pnpm.io/filtering
+-->

.agents/skills/pnpm/references/core-config.md

@@ -0,0 +1,188 @@
+---
+name: pnpm-configuration
+description: Configuration options via pnpm-workspace.yaml and .npmrc settings
+---
+
+# pnpm Configuration
+
+pnpm uses two main configuration files: `pnpm-workspace.yaml` for workspace and pnpm-specific settings, and `.npmrc` for npm-compatible and pnpm-specific settings.
+
+## pnpm-workspace.yaml
+
+The recommended location for pnpm-specific configurations. Place at project root.
+
+```yaml
+# Define workspace packages
+packages:
+  - 'packages/*'
+  - 'apps/*'
+  - '!**/test/**'  # Exclude pattern
+
+# Catalog for shared dependency versions
+catalog:
+  react: ^18.2.0
+  typescript: ~5.3.0
+
+# Named catalogs for different dependency groups
+catalogs:
+  react17:
+    react: ^17.0.2
+    react-dom: ^17.0.2
+  react18:
+    react: ^18.2.0
+    react-dom: ^18.2.0
+
+# Override resolutions (preferred location)
+overrides:
+  lodash: ^4.17.21
+  'foo@^1.0.0>bar': ^2.0.0
+
+# pnpm settings (alternative to .npmrc)
+settings:
+  auto-install-peers: true
+  strict-peer-dependencies: false
+  link-workspace-packages: true
+  prefer-workspace-packages: true
+  shared-workspace-lockfile: true
+```
+
+## .npmrc Settings
+
+pnpm reads settings from `.npmrc` files. Create at project root or user home.
+
+### Common pnpm Settings
+
+```ini
+# Automatically install peer dependencies
+auto-install-peers=true
+
+# Fail on peer dependency issues
+strict-peer-dependencies=false
+
+# Hoist patterns for dependencies
+public-hoist-pattern[]=*types*
+public-hoist-pattern[]=*eslint*
+shamefully-hoist=false
+
+# Store location
+store-dir=~/.pnpm-store
+
+# Virtual store location  
+virtual-store-dir=node_modules/.pnpm
+
+# Lockfile settings
+lockfile=true
+prefer-frozen-lockfile=true
+
+# Side effects cache (speeds up rebuilds)
+side-effects-cache=true
+
+# Registry settings
+registry=https://registry.npmjs.org/
+@myorg:registry=https://npm.myorg.com/
+```
+
+### Workspace Settings
+
+```ini
+# Link workspace packages
+link-workspace-packages=true
+
+# Prefer workspace packages over registry
+prefer-workspace-packages=true
+
+# Single lockfile for all packages
+shared-workspace-lockfile=true
+
+# Save prefix for workspace dependencies
+save-workspace-protocol=rolling
+```
+
+### Node.js Settings
+
+```ini
+# Use specific Node.js version
+use-node-version=20.10.0
+
+# Node.js version file
+node-version-file=.nvmrc
+
+# Manage Node.js versions
+manage-package-manager-versions=true
+```
+
+### Security Settings
+
+```ini
+# Ignore specific scripts
+ignore-scripts=false
+
+# Allow specific build scripts
+onlyBuiltDependencies[]=esbuild
+onlyBuiltDependencies[]=sharp
+
+# Package extensions for missing peer deps
+package-extensions[foo@1].peerDependencies.bar=*
+```
+
+## Configuration Hierarchy
+
+Settings are read in order (later overrides earlier):
+
+1. `/etc/npmrc` - Global config
+2. `~/.npmrc` - User config  
+3. `<project>/.npmrc` - Project config
+4. Environment variables: `npm_config_<key>=<value>`
+5. `pnpm-workspace.yaml` settings field
+
+## Environment Variables
+
+```bash
+# Set config via env
+npm_config_registry=https://registry.npmjs.org/
+
+# pnpm-specific env vars
+PNPM_HOME=~/.local/share/pnpm
+```
+
+## Package.json Fields
+
+pnpm reads specific fields from `package.json`:
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "lodash": "^4.17.21"
+    },
+    "peerDependencyRules": {
+      "ignoreMissing": ["@babel/*"],
+      "allowedVersions": {
+        "react": "17 || 18"
+      }
+    },
+    "neverBuiltDependencies": ["fsevents"],
+    "onlyBuiltDependencies": ["esbuild"],
+    "allowedDeprecatedVersions": {
+      "request": "*"
+    },
+    "patchedDependencies": {
+      "express@4.18.2": "patches/express@4.18.2.patch"
+    }
+  }
+}
+```
+
+## Key Differences from npm/yarn
+
+1. **Strict by default**: No phantom dependencies
+2. **Workspace protocol**: `workspace:*` for local packages
+3. **Catalogs**: Centralized version management
+4. **Content-addressable store**: Shared across projects
+
+<!-- 
+Source references:
+- https://pnpm.io/pnpm-workspace_yaml
+- https://pnpm.io/npmrc
+- https://pnpm.io/package_json
+-->

.agents/skills/pnpm/references/core-store.md

@@ -0,0 +1,179 @@
+---
+name: pnpm-store
+description: Content-addressable storage system that makes pnpm fast and disk-efficient
+---
+
+# pnpm Store
+
+pnpm uses a content-addressable store to save disk space and speed up installations. All packages are stored once globally and hard-linked to project `node_modules`.
+
+## How It Works
+
+1. **Global Store**: Packages are downloaded once to a central store
+2. **Hard Links**: Projects link to store instead of copying files
+3. **Content-Addressable**: Files are stored by content hash, deduplicating identical files
+
+### Storage Layout
+
+```
+~/.pnpm-store/              # Global store (default location)
+└── v3/
+    └── files/
+        └── <hash>/         # Files stored by content hash
+
+project/
+└── node_modules/
+    ├── .pnpm/              # Virtual store (hard links to global store)
+    │   ├── lodash@4.17.21/
+    │   │   └── node_modules/
+    │   │       └── lodash/
+    │   └── express@4.18.2/
+    │       └── node_modules/
+    │           ├── express/
+    │           └── <deps>/  # Flat structure for dependencies
+    ├── lodash -> .pnpm/lodash@4.17.21/node_modules/lodash
+    └── express -> .pnpm/express@4.18.2/node_modules/express
+```
+
+## Store Commands
+
+```bash
+# Show store location
+pnpm store path
+
+# Remove unreferenced packages
+pnpm store prune
+
+# Check store integrity
+pnpm store status
+
+# Add package to store without installing
+pnpm store add <pkg>
+```
+
+## Configuration
+
+### Store Location
+
+```ini
+# .npmrc
+store-dir=~/.pnpm-store
+
+# Or use environment variable
+PNPM_HOME=~/.local/share/pnpm
+```
+
+### Virtual Store
+
+The virtual store (`.pnpm` in `node_modules`) contains symlinks to the global store:
+
+```ini
+# Customize virtual store location
+virtual-store-dir=node_modules/.pnpm
+
+# Alternative flat layout
+node-linker=hoisted
+```
+
+## Disk Space Benefits
+
+pnpm saves significant disk space:
+
+- **Deduplication**: Same package version stored once across all projects
+- **Content deduplication**: Identical files across different packages stored once
+- **Hard links**: No copying, just linking
+
+### Check disk usage
+
+```bash
+# Compare actual vs apparent size
+du -sh node_modules        # Apparent size
+du -sh --apparent-size node_modules  # With hard links counted
+```
+
+## Node Linker Modes
+
+Configure how `node_modules` is structured:
+
+```ini
+# Default: Symlinked structure (recommended)
+node-linker=isolated
+
+# Flat node_modules (npm-like, for compatibility)
+node-linker=hoisted
+
+# PnP mode (experimental, like Yarn PnP)
+node-linker=pnp
+```
+
+### Isolated Mode (Default)
+
+- Strict dependency resolution
+- No phantom dependencies
+- Packages can only access declared dependencies
+
+### Hoisted Mode
+
+- Flat `node_modules` like npm
+- For compatibility with tools that don't support symlinks
+- Loses strictness benefits
+
+## Side Effects Cache
+
+Cache build outputs for native modules:
+
+```ini
+# Enable side effects caching
+side-effects-cache=true
+
+# Store side effects in project (instead of global store)
+side-effects-cache-readonly=true
+```
+
+## Shared Store Across Machines
+
+For CI/CD, you can share the store:
+
+```yaml
+# GitHub Actions example
+- uses: pnpm/action-setup@v4
+  with:
+    run_install: false
+
+- name: Get pnpm store directory
+  shell: bash
+  run: echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+
+- uses: actions/cache@v4
+  with:
+    path: ${{ env.STORE_PATH }}
+    key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+```
+
+## Troubleshooting
+
+### Store corruption
+```bash
+# Verify and fix store
+pnpm store status
+pnpm store prune
+```
+
+### Hard link issues (network drives, Docker)
+```ini
+# Use copying instead of hard links
+package-import-method=copy
+```
+
+### Permission issues
+```bash
+# Fix store permissions
+chmod -R u+w ~/.pnpm-store
+```
+
+<!-- 
+Source references:
+- https://pnpm.io/symlinked-node-modules-structure
+- https://pnpm.io/cli/store
+- https://pnpm.io/npmrc#store-dir
+-->

.agents/skills/pnpm/references/core-workspaces.md

@@ -0,0 +1,205 @@
+---
+name: pnpm-workspaces
+description: Monorepo support with workspaces for managing multiple packages
+---
+
+# pnpm Workspaces
+
+pnpm has built-in support for monorepos (multi-package repositories) through workspaces.
+
+## Setting Up Workspaces
+
+Create `pnpm-workspace.yaml` at the repository root:
+
+```yaml
+packages:
+  # Include all packages in packages/ directory
+  - 'packages/*'
+  # Include all apps
+  - 'apps/*'
+  # Include nested packages
+  - 'tools/*/packages/*'
+  # Exclude test directories
+  - '!**/test/**'
+```
+
+## Workspace Protocol
+
+Use `workspace:` protocol to reference local packages:
+
+```json
+{
+  "dependencies": {
+    "@myorg/utils": "workspace:*",
+    "@myorg/core": "workspace:^",
+    "@myorg/types": "workspace:~"
+  }
+}
+```
+
+### Protocol Variants
+
+| Protocol | Behavior | Published As |
+|----------|----------|--------------|
+| `workspace:*` | Any version | Actual version (e.g., `1.2.3`) |
+| `workspace:^` | Compatible version | `^1.2.3` |
+| `workspace:~` | Patch version | `~1.2.3` |
+| `workspace:^1.0.0` | Semver range | `^1.0.0` |
+
+## Filtering Packages
+
+Run commands on specific packages using `--filter`:
+
+```bash
+# By package name
+pnpm --filter @myorg/app build
+pnpm -F @myorg/app build
+
+# By directory path
+pnpm --filter "./packages/core" test
+
+# Glob patterns
+pnpm --filter "@myorg/*" lint
+pnpm --filter "!@myorg/internal-*" publish
+
+# All packages
+pnpm -r build
+pnpm --recursive build
+```
+
+### Dependency-based Filtering
+
+```bash
+# Package and all its dependencies
+pnpm --filter "...@myorg/app" build
+
+# Package and all its dependents
+pnpm --filter "@myorg/core..." test
+
+# Both directions
+pnpm --filter "...@myorg/shared..." build
+
+# Changed since git ref
+pnpm --filter "...[origin/main]" test
+pnpm --filter "[HEAD~5]" lint
+```
+
+## Workspace Commands
+
+### Install dependencies
+```bash
+# Install all workspace packages
+pnpm install
+
+# Add dependency to specific package
+pnpm --filter @myorg/app add lodash
+
+# Add workspace dependency
+pnpm --filter @myorg/app add @myorg/utils
+```
+
+### Run scripts
+```bash
+# Run in all packages with that script
+pnpm -r run build
+
+# Run in topological order (dependencies first)
+pnpm -r --workspace-concurrency=1 run build
+
+# Run in parallel
+pnpm -r --parallel run test
+
+# Stream output
+pnpm -r --stream run dev
+```
+
+### Execute commands
+```bash
+# Run command in all packages
+pnpm -r exec pwd
+
+# Run in specific packages
+pnpm --filter "./packages/**" exec rm -rf dist
+```
+
+## Workspace Settings
+
+Configure in `.npmrc` or `pnpm-workspace.yaml`:
+
+```ini
+# Link workspace packages automatically
+link-workspace-packages=true
+
+# Prefer workspace packages over registry
+prefer-workspace-packages=true
+
+# Single lockfile (recommended)
+shared-workspace-lockfile=true
+
+# Workspace protocol handling
+save-workspace-protocol=rolling
+
+# Concurrent workspace scripts
+workspace-concurrency=4
+```
+
+## Publishing Workspaces
+
+When publishing, `workspace:` protocols are converted:
+
+```json
+// Before publish
+{
+  "dependencies": {
+    "@myorg/utils": "workspace:^"
+  }
+}
+
+// After publish
+{
+  "dependencies": {
+    "@myorg/utils": "^1.2.3"
+  }
+}
+```
+
+Use `--no-git-checks` for publishing from CI:
+```bash
+pnpm publish -r --no-git-checks
+```
+
+## Best Practices
+
+1. **Use workspace protocol** for internal dependencies
+2. **Enable `link-workspace-packages`** for automatic linking
+3. **Use shared lockfile** for consistency
+4. **Filter by dependencies** when building to ensure correct order
+5. **Use catalogs** for shared external dependency versions
+
+## Example Project Structure
+
+```
+my-monorepo/
+├── pnpm-workspace.yaml
+├── package.json
+├── pnpm-lock.yaml
+├── packages/
+│   ├── core/
+│   │   └── package.json
+│   ├── utils/
+│   │   └── package.json
+│   └── types/
+│       └── package.json
+└── apps/
+    ├── web/
+    │   └── package.json
+    └── api/
+        └── package.json
+```
+
+<!-- 
+Source references:
+- https://pnpm.io/workspaces
+- https://pnpm.io/filtering
+- https://pnpm.io/npmrc#workspace-settings
+-->

.agents/skills/pnpm/references/features-aliases.md

@@ -0,0 +1,168 @@
+---
+name: pnpm-aliases
+description: Install packages under custom names for versioning, forks, or alternatives
+---
+
+# pnpm Aliases
+
+pnpm supports package aliases using the `npm:` protocol. This lets you install packages under different names, use multiple versions of the same package, or substitute packages.
+
+## Basic Syntax
+
+```bash
+pnpm add <alias>@npm:<package>@<version>
+```
+
+In `package.json`:
+```json
+{
+  "dependencies": {
+    "<alias>": "npm:<package>@<version>"
+  }
+}
+```
+
+## Use Cases
+
+### Multiple Versions of Same Package
+
+Install different versions side by side:
+
+```json
+{
+  "dependencies": {
+    "lodash3": "npm:lodash@3",
+    "lodash4": "npm:lodash@4"
+  }
+}
+```
+
+Usage:
+```js
+import lodash3 from 'lodash3'
+import lodash4 from 'lodash4'
+```
+
+### Replace Package with Fork
+
+Substitute a package with a fork or alternative:
+
+```json
+{
+  "dependencies": {
+    "original-pkg": "npm:my-fork@^1.0.0"
+  }
+}
+```
+
+All imports of `original-pkg` will resolve to `my-fork`.
+
+### Replace Deprecated Package
+
+```json
+{
+  "dependencies": {
+    "request": "npm:@cypress/request@^3.0.0"
+  }
+}
+```
+
+### Scoped to Unscoped (or vice versa)
+
+```json
+{
+  "dependencies": {
+    "vue": "npm:@anthropic/vue@^3.0.0",
+    "@myorg/utils": "npm:lodash@^4.17.21"
+  }
+}
+```
+
+## CLI Usage
+
+### Add with alias
+
+```bash
+# Add lodash under alias
+pnpm add lodash4@npm:lodash@4
+
+# Add fork as original name
+pnpm add request@npm:@cypress/request
+```
+
+### Add multiple versions
+
+```bash
+pnpm add react17@npm:react@17 react18@npm:react@18
+```
+
+## With TypeScript
+
+For type resolution with aliases, you may need to configure TypeScript:
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "paths": {
+      "lodash3": ["node_modules/lodash3"],
+      "lodash4": ["node_modules/lodash4"]
+    }
+  }
+}
+```
+
+Or use `@types` packages with aliases:
+
+```json
+{
+  "devDependencies": {
+    "@types/lodash3": "npm:@types/lodash@3",
+    "@types/lodash4": "npm:@types/lodash@4"
+  }
+}
+```
+
+## Combined with Overrides
+
+Force all transitive dependencies to use an alias:
+
+```yaml
+# pnpm-workspace.yaml
+overrides:
+  "underscore": "npm:lodash@^4.17.21"
+```
+
+This replaces all `underscore` imports (including in dependencies) with lodash.
+
+## Git and Local Aliases
+
+Aliases work with any valid pnpm specifier:
+
+```json
+{
+  "dependencies": {
+    "my-fork": "npm:user/repo#commit",
+    "local-pkg": "file:../local-package"
+  }
+}
+```
+
+## Best Practices
+
+1. **Clear naming**: Use descriptive alias names that indicate purpose
+   ```json
+   "lodash-legacy": "npm:lodash@3"
+   "lodash-modern": "npm:lodash@4"
+   ```
+
+2. **Document aliases**: Add comments or documentation explaining why aliases exist
+
+3. **Prefer overrides for global replacement**: If you want to replace a package everywhere, use overrides instead of aliases
+
+4. **Test thoroughly**: Aliased packages may have subtle differences in behavior
+
+<!-- 
+Source references:
+- https://pnpm.io/aliases
+-->

.agents/skills/pnpm/references/features-catalogs.md

@@ -0,0 +1,159 @@
+---
+name: pnpm-catalogs
+description: Centralized dependency version management for workspaces
+---
+
+# pnpm Catalogs
+
+Catalogs provide a centralized way to manage dependency versions across a workspace. Define versions once, use everywhere.
+
+## Basic Usage
+
+Define a catalog in `pnpm-workspace.yaml`:
+
+```yaml
+packages:
+  - 'packages/*'
+
+catalog:
+  react: ^18.2.0
+  react-dom: ^18.2.0
+  typescript: ~5.3.0
+  vite: ^5.0.0
+```
+
+Reference in `package.json` with `catalog:`:
+
+```json
+{
+  "dependencies": {
+    "react": "catalog:",
+    "react-dom": "catalog:"
+  },
+  "devDependencies": {
+    "typescript": "catalog:",
+    "vite": "catalog:"
+  }
+}
+```
+
+## Named Catalogs
+
+Create multiple catalogs for different scenarios:
+
+```yaml
+packages:
+  - 'packages/*'
+
+# Default catalog
+catalog:
+  lodash: ^4.17.21
+
+# Named catalogs
+catalogs:
+  react17:
+    react: ^17.0.2
+    react-dom: ^17.0.2
+  
+  react18:
+    react: ^18.2.0
+    react-dom: ^18.2.0
+  
+  testing:
+    vitest: ^1.0.0
+    "@testing-library/react": ^14.0.0
+```
+
+Reference named catalogs:
+
+```json
+{
+  "dependencies": {
+    "react": "catalog:react18",
+    "react-dom": "catalog:react18"
+  },
+  "devDependencies": {
+    "vitest": "catalog:testing"
+  }
+}
+```
+
+## Benefits
+
+1. **Single source of truth**: Update version in one place
+2. **Consistency**: All packages use the same version
+3. **Easy upgrades**: Change version once, affects entire workspace
+4. **Type-safe**: TypeScript support in pnpm-workspace.yaml
+
+## Catalog vs Overrides
+
+| Feature | Catalogs | Overrides |
+|---------|----------|-----------|
+| Purpose | Define versions for direct dependencies | Force versions for any dependency |
+| Scope | Direct dependencies only | All dependencies (including transitive) |
+| Usage | `"pkg": "catalog:"` | Applied automatically |
+| Opt-in | Explicit per package.json | Global to workspace |
+
+## Publishing with Catalogs
+
+When publishing, `catalog:` references are replaced with actual versions:
+
+```json
+// Before publish (source)
+{
+  "dependencies": {
+    "react": "catalog:"
+  }
+}
+
+// After publish (published package)
+{
+  "dependencies": {
+    "react": "^18.2.0"
+  }
+}
+```
+
+## Migration from Overrides
+
+If you're using overrides for version consistency:
+
+```yaml
+# Before (using overrides)
+overrides:
+  react: ^18.2.0
+  react-dom: ^18.2.0
+```
+
+Migrate to catalogs for cleaner dependency management:
+
+```yaml
+# After (using catalogs)
+catalog:
+  react: ^18.2.0
+  react-dom: ^18.2.0
+```
+
+Then update package.json files to use `catalog:`.
+
+## Best Practices
+
+1. **Use default catalog** for commonly shared dependencies
+2. **Use named catalogs** for version variants (e.g., different React versions)
+3. **Keep catalog minimal** - only include shared dependencies
+4. **Combine with workspace protocol** for internal packages
+
+```yaml
+catalog:
+  # External shared dependencies
+  lodash: ^4.17.21
+  zod: ^3.22.0
+
+# Internal packages use workspace: protocol instead
+# "dependencies": { "@myorg/utils": "workspace:^" }
+```
+
+<!-- 
+Source references:
+- https://pnpm.io/catalogs
+-->

.agents/skills/pnpm/references/features-hooks.md

@@ -0,0 +1,233 @@
+---
+name: pnpm-hooks
+description: Customize package resolution and dependency behavior with pnpmfile hooks
+---
+
+# pnpm Hooks
+
+pnpm provides hooks via `.pnpmfile.cjs` to customize how packages are resolved and their metadata is processed.
+
+## Setup
+
+Create `.pnpmfile.cjs` at workspace root:
+
+```js
+// .pnpmfile.cjs
+function readPackage(pkg, context) {
+  // Modify package metadata
+  return pkg
+}
+
+function afterAllResolved(lockfile, context) {
+  // Modify lockfile
+  return lockfile
+}
+
+module.exports = {
+  hooks: {
+    readPackage,
+    afterAllResolved
+  }
+}
+```
+
+## readPackage Hook
+
+Called for every package before resolution. Use to modify dependencies, add missing peer deps, or fix broken packages.
+
+### Add Missing Peer Dependency
+
+```js
+function readPackage(pkg, context) {
+  if (pkg.name === 'some-broken-package') {
+    pkg.peerDependencies = {
+      ...pkg.peerDependencies,
+      react: '*'
+    }
+    context.log(`Added react peer dep to ${pkg.name}`)
+  }
+  return pkg
+}
+```
+
+### Override Dependency Version
+
+```js
+function readPackage(pkg, context) {
+  // Fix all lodash versions
+  if (pkg.dependencies?.lodash) {
+    pkg.dependencies.lodash = '^4.17.21'
+  }
+  if (pkg.devDependencies?.lodash) {
+    pkg.devDependencies.lodash = '^4.17.21'
+  }
+  return pkg
+}
+```
+
+### Remove Unwanted Dependency
+
+```js
+function readPackage(pkg, context) {
+  // Remove optional dependency that causes issues
+  if (pkg.optionalDependencies?.fsevents) {
+    delete pkg.optionalDependencies.fsevents
+  }
+  return pkg
+}
+```
+
+### Replace Package
+
+```js
+function readPackage(pkg, context) {
+  // Replace deprecated package
+  if (pkg.dependencies?.['old-package']) {
+    pkg.dependencies['new-package'] = pkg.dependencies['old-package']
+    delete pkg.dependencies['old-package']
+  }
+  return pkg
+}
+```
+
+### Fix Broken Package
+
+```js
+function readPackage(pkg, context) {
+  // Fix incorrect exports field
+  if (pkg.name === 'broken-esm-package') {
+    pkg.exports = {
+      '.': {
+        import: './dist/index.mjs',
+        require: './dist/index.cjs'
+      }
+    }
+  }
+  return pkg
+}
+```
+
+## afterAllResolved Hook
+
+Called after the lockfile is generated. Use for post-resolution modifications.
+
+```js
+function afterAllResolved(lockfile, context) {
+  // Log all resolved packages
+  context.log(`Resolved ${Object.keys(lockfile.packages || {}).length} packages`)
+  
+  // Modify lockfile if needed
+  return lockfile
+}
+```
+
+## Context Object
+
+The `context` object provides utilities:
+
+```js
+function readPackage(pkg, context) {
+  // Log messages
+  context.log('Processing package...')
+  
+  return pkg
+}
+```
+
+## Use with TypeScript
+
+For type hints, use JSDoc:
+
+```js
+// .pnpmfile.cjs
+
+/**
+ * @param {import('type-fest').PackageJson} pkg
+ * @param {{ log: (msg: string) => void }} context
+ * @returns {import('type-fest').PackageJson}
+ */
+function readPackage(pkg, context) {
+  return pkg
+}
+
+module.exports = {
+  hooks: {
+    readPackage
+  }
+}
+```
+
+## Common Patterns
+
+### Conditional by Package Name
+
+```js
+function readPackage(pkg, context) {
+  switch (pkg.name) {
+    case 'package-a':
+      pkg.dependencies.foo = '^2.0.0'
+      break
+    case 'package-b':
+      delete pkg.optionalDependencies.bar
+      break
+  }
+  return pkg
+}
+```
+
+### Apply to All Packages
+
+```js
+function readPackage(pkg, context) {
+  // Remove all optional fsevents
+  if (pkg.optionalDependencies) {
+    delete pkg.optionalDependencies.fsevents
+  }
+  return pkg
+}
+```
+
+### Debug Resolution
+
+```js
+function readPackage(pkg, context) {
+  if (process.env.DEBUG_PNPM) {
+    context.log(`${pkg.name}@${pkg.version}`)
+    context.log(`  deps: ${Object.keys(pkg.dependencies || {}).join(', ')}`)
+  }
+  return pkg
+}
+```
+
+## Hooks vs Overrides
+
+| Feature | Hooks (.pnpmfile.cjs) | Overrides |
+|---------|----------------------|-----------|
+| Complexity | Can use JavaScript logic | Declarative only |
+| Scope | Any package metadata | Version only |
+| Use case | Complex fixes, conditional logic | Simple version pins |
+
+**Prefer overrides** for simple version fixes. **Use hooks** when you need:
+- Conditional logic
+- Non-version modifications (exports, peer deps)
+- Logging/debugging
+
+## Troubleshooting
+
+### Hook not running
+
+1. Ensure file is named `.pnpmfile.cjs` (not `.js`)
+2. Check file is at workspace root
+3. Run `pnpm install` to trigger hooks
+
+### Debug hooks
+
+```bash
+# See hook logs
+pnpm install --reporter=append-only
+```
+
+<!-- 
+Source references:
+- https://pnpm.io/pnpmfile
+-->

.agents/skills/pnpm/references/features-overrides.md

@@ -0,0 +1,184 @@
+---
+name: pnpm-overrides
+description: Force specific versions of dependencies including transitive dependencies
+---
+
+# pnpm Overrides
+
+Overrides let you force specific versions of packages, including transitive dependencies. Useful for fixing security vulnerabilities or compatibility issues.
+
+## Basic Syntax
+
+Define overrides in `pnpm-workspace.yaml` (recommended) or `package.json`:
+
+### In pnpm-workspace.yaml (Recommended)
+
+```yaml
+packages:
+  - 'packages/*'
+
+overrides:
+  # Override all versions of a package
+  lodash: ^4.17.21
+  
+  # Override specific version range
+  "foo@^1.0.0": ^1.2.3
+  
+  # Override nested dependency
+  "express>cookie": ^0.6.0
+  
+  # Override to different package
+  "underscore": "npm:lodash@^4.17.21"
+```
+
+### In package.json
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "lodash": "^4.17.21",
+      "foo@^1.0.0": "^1.2.3",
+      "bar@^2.0.0>qux": "^1.0.0"
+    }
+  }
+}
+```
+
+## Override Patterns
+
+### Override all instances
+```yaml
+overrides:
+  lodash: ^4.17.21
+```
+Forces all lodash installations to use ^4.17.21.
+
+### Override specific parent version
+```yaml
+overrides:
+  "foo@^1.0.0": ^1.2.3
+```
+Only override foo when the requested version matches ^1.0.0.
+
+### Override nested dependency
+```yaml
+overrides:
+  "express>cookie": ^0.6.0
+  "foo@1.x>bar@^2.0.0>qux": ^1.0.0
+```
+Override cookie only when it's a dependency of express.
+
+### Replace with different package
+```yaml
+overrides:
+  # Replace underscore with lodash
+  "underscore": "npm:lodash@^4.17.21"
+  
+  # Use local file
+  "some-pkg": "file:./local-pkg"
+  
+  # Use git
+  "some-pkg": "github:user/repo#commit"
+```
+
+### Remove a dependency
+```yaml
+overrides:
+  "unwanted-pkg": "-"
+```
+The `-` removes the package entirely.
+
+## Common Use Cases
+
+### Security Fix
+
+Force patched version of vulnerable package:
+
+```yaml
+overrides:
+  # Fix CVE in transitive dependency
+  "minimist": "^1.2.6"
+  "json5": "^2.2.3"
+```
+
+### Deduplicate Dependencies
+
+Force single version when multiple are installed:
+
+```yaml
+overrides:
+  "react": "^18.2.0"
+  "react-dom": "^18.2.0"
+```
+
+### Fix Peer Dependency Issues
+
+```yaml
+overrides:
+  "@types/react": "^18.2.0"
+```
+
+### Replace Deprecated Package
+
+```yaml
+overrides:
+  "request": "npm:@cypress/request@^3.0.0"
+```
+
+## Hooks Alternative
+
+For more complex scenarios, use `.pnpmfile.cjs`:
+
+```js
+// .pnpmfile.cjs
+function readPackage(pkg, context) {
+  // Override dependency version
+  if (pkg.dependencies?.lodash) {
+    pkg.dependencies.lodash = '^4.17.21'
+  }
+  
+  // Add missing peer dependency
+  if (pkg.name === 'some-package') {
+    pkg.peerDependencies = {
+      ...pkg.peerDependencies,
+      react: '*'
+    }
+  }
+  
+  return pkg
+}
+
+module.exports = {
+  hooks: {
+    readPackage
+  }
+}
+```
+
+## Overrides vs Catalogs
+
+| Feature | Overrides | Catalogs |
+|---------|-----------|----------|
+| Affects | All dependencies (including transitive) | Direct dependencies only |
+| Usage | Automatic | Explicit `catalog:` reference |
+| Purpose | Force versions, fix issues | Version management |
+| Granularity | Can target specific parents | Package-wide only |
+
+## Debugging
+
+Check which version is resolved:
+
+```bash
+# See resolved versions
+pnpm why lodash
+
+# List all versions
+pnpm list lodash --depth=Infinity
+```
+
+<!-- 
+Source references:
+- https://pnpm.io/package_json#pnpmoverrides
+- https://pnpm.io/pnpmfile
+-->

.agents/skills/pnpm/references/features-patches.md

@@ -0,0 +1,201 @@
+---
+name: pnpm-patches
+description: Patch third-party packages directly with customized fixes
+---
+
+# pnpm Patches
+
+pnpm's patching feature lets you modify third-party packages directly. Useful for applying fixes before upstream releases or customizing package behavior.
+
+## Creating a Patch
+
+### Step 1: Initialize Patch
+
+```bash
+pnpm patch <pkg>@<version>
+
+# Example
+pnpm patch express@4.18.2
+```
+
+This creates a temporary directory with the package source and outputs the path:
+
+```
+You can now edit the following folder: /tmp/abc123...
+```
+
+### Step 2: Edit Files
+
+Navigate to the temporary directory and make your changes:
+
+```bash
+cd /tmp/abc123...
+# Edit files as needed
+```
+
+### Step 3: Commit Patch
+
+```bash
+pnpm patch-commit <path-from-step-1>
+
+# Example
+pnpm patch-commit /tmp/abc123...
+```
+
+This creates a `.patch` file in `patches/` and updates `package.json`:
+
+```
+patches/
+└── express@4.18.2.patch
+```
+
+```json
+{
+  "pnpm": {
+    "patchedDependencies": {
+      "express@4.18.2": "patches/express@4.18.2.patch"
+    }
+  }
+}
+```
+
+## Patch File Format
+
+Patches use standard unified diff format:
+
+```diff
+diff --git a/lib/router/index.js b/lib/router/index.js
+index abc123..def456 100644
+--- a/lib/router/index.js
++++ b/lib/router/index.js
+@@ -100,6 +100,7 @@ function createRouter() {
+   // Original code
+-  const timeout = 30000;
++  const timeout = 60000; // Extended timeout
+   return router;
+ }
+```
+
+## Managing Patches
+
+### List Patched Packages
+
+```bash
+pnpm list --depth=0
+# Shows (patched) marker for patched packages
+```
+
+### Update a Patch
+
+```bash
+# Edit existing patch
+pnpm patch express@4.18.2
+
+# After editing
+pnpm patch-commit <path>
+```
+
+### Remove a Patch
+
+```bash
+pnpm patch-remove <pkg>@<version>
+
+# Example  
+pnpm patch-remove express@4.18.2
+```
+
+Or manually:
+1. Delete the patch file from `patches/`
+2. Remove entry from `patchedDependencies` in `package.json`
+3. Run `pnpm install`
+
+## Patch Configuration
+
+### Custom Patches Directory
+
+```json
+{
+  "pnpm": {
+    "patchedDependencies": {
+      "express@4.18.2": "custom-patches/my-express-fix.patch"
+    }
+  }
+}
+```
+
+### Multiple Packages
+
+```json
+{
+  "pnpm": {
+    "patchedDependencies": {
+      "express@4.18.2": "patches/express@4.18.2.patch",
+      "lodash@4.17.21": "patches/lodash@4.17.21.patch",
+      "@types/node@20.10.0": "patches/@types__node@20.10.0.patch"
+    }
+  }
+}
+```
+
+## Workspaces
+
+Patches are shared across the workspace. Define in the root `package.json`:
+
+```json
+// Root package.json
+{
+  "pnpm": {
+    "patchedDependencies": {
+      "express@4.18.2": "patches/express@4.18.2.patch"
+    }
+  }
+}
+```
+
+All workspace packages using `express@4.18.2` will have the patch applied.
+
+## Best Practices
+
+1. **Version specificity**: Patches are tied to exact versions. Update patches when upgrading dependencies.
+
+2. **Document patches**: Add comments explaining why the patch exists:
+   ```bash
+   # In patches/README.md
+   ## express@4.18.2.patch
+   Fixes timeout issue. PR pending: https://github.com/expressjs/express/pull/1234
+   ```
+
+3. **Minimize patches**: Keep patches small and focused. Large patches are hard to maintain.
+
+4. **Track upstream**: Note upstream issues/PRs so you can remove patches when fixed.
+
+5. **Test patches**: Ensure patched code works correctly in your use case.
+
+## Troubleshooting
+
+### Patch fails to apply
+
+```
+ERR_PNPM_PATCH_FAILED  Cannot apply patch
+```
+
+The package version changed. Recreate the patch:
+```bash
+pnpm patch-remove express@4.18.2
+pnpm patch express@4.18.2
+# Reapply changes
+pnpm patch-commit <path>
+```
+
+### Patch not applied
+
+Ensure:
+1. Version in `patchedDependencies` matches installed version exactly
+2. Run `pnpm install` after adding patch configuration
+
+<!-- 
+Source references:
+- https://pnpm.io/cli/patch
+- https://pnpm.io/cli/patch-commit
+- https://pnpm.io/package_json#pnpmpatcheddependencies
+-->

.agents/skills/pnpm/references/features-peer-deps.md

@@ -0,0 +1,250 @@
+---
+name: pnpm-peer-dependencies
+description: Handling peer dependencies with auto-install and resolution rules
+---
+
+# pnpm Peer Dependencies
+
+pnpm has strict peer dependency handling by default. It provides configuration options to control how peer dependencies are resolved and reported.
+
+## Auto-Install Peer Dependencies
+
+By default, pnpm automatically installs peer dependencies:
+
+```ini
+# .npmrc (default is true since pnpm v8)
+auto-install-peers=true
+```
+
+When enabled, pnpm automatically adds missing peer dependencies based on the best matching version.
+
+## Strict Peer Dependencies
+
+Control whether peer dependency issues cause errors:
+
+```ini
+# Fail on peer dependency issues (default: false)
+strict-peer-dependencies=true
+```
+
+When strict, pnpm will fail if:
+- Peer dependency is missing
+- Installed version doesn't match required range
+
+## Peer Dependency Rules
+
+Configure peer dependency behavior in `package.json`:
+
+```json
+{
+  "pnpm": {
+    "peerDependencyRules": {
+      "ignoreMissing": ["@babel/*", "eslint"],
+      "allowedVersions": {
+        "react": "17 || 18"
+      },
+      "allowAny": ["@types/*"]
+    }
+  }
+}
+```
+
+### ignoreMissing
+
+Suppress warnings for missing peer dependencies:
+
+```json
+{
+  "pnpm": {
+    "peerDependencyRules": {
+      "ignoreMissing": [
+        "@babel/*",
+        "eslint",
+        "webpack"
+      ]
+    }
+  }
+}
+```
+
+Use patterns:
+- `"react"` - exact package name
+- `"@babel/*"` - all packages in scope
+- `"*"` - all packages (not recommended)
+
+### allowedVersions
+
+Allow specific versions that would otherwise cause warnings:
+
+```json
+{
+  "pnpm": {
+    "peerDependencyRules": {
+      "allowedVersions": {
+        "react": "17 || 18",
+        "webpack": "4 || 5",
+        "@types/react": "*"
+      }
+    }
+  }
+}
+```
+
+### allowAny
+
+Allow any version for specified peer dependencies:
+
+```json
+{
+  "pnpm": {
+    "peerDependencyRules": {
+      "allowAny": ["@types/*", "eslint"]
+    }
+  }
+}
+```
+
+## Adding Peer Dependencies via Hooks
+
+Use `.pnpmfile.cjs` to add missing peer dependencies:
+
+```js
+// .pnpmfile.cjs
+function readPackage(pkg, context) {
+  // Add missing peer dependency
+  if (pkg.name === 'problematic-package') {
+    pkg.peerDependencies = {
+      ...pkg.peerDependencies,
+      react: '*'
+    }
+  }
+  return pkg
+}
+
+module.exports = {
+  hooks: {
+    readPackage
+  }
+}
+```
+
+## Peer Dependencies in Workspaces
+
+Workspace packages can satisfy peer dependencies:
+
+```json
+// packages/app/package.json
+{
+  "dependencies": {
+    "react": "^18.2.0",
+    "@myorg/components": "workspace:^"
+  }
+}
+
+// packages/components/package.json  
+{
+  "peerDependencies": {
+    "react": "^17.0.0 || ^18.0.0"
+  }
+}
+```
+
+The workspace `app` provides `react` which satisfies `components`' peer dependency.
+
+## Common Scenarios
+
+### Monorepo with Shared React
+
+```yaml
+# pnpm-workspace.yaml
+catalog:
+  react: ^18.2.0
+  react-dom: ^18.2.0
+```
+
+```json
+// packages/ui/package.json
+{
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  }
+}
+
+// apps/web/package.json
+{
+  "dependencies": {
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "@myorg/ui": "workspace:^"
+  }
+}
+```
+
+### Suppress ESLint Plugin Warnings
+
+```json
+{
+  "pnpm": {
+    "peerDependencyRules": {
+      "ignoreMissing": [
+        "eslint",
+        "@typescript-eslint/parser"
+      ]
+    }
+  }
+}
+```
+
+### Allow Multiple Major Versions
+
+```json
+{
+  "pnpm": {
+    "peerDependencyRules": {
+      "allowedVersions": {
+        "webpack": "4 || 5",
+        "postcss": "7 || 8"
+      }
+    }
+  }
+}
+```
+
+## Debugging Peer Dependencies
+
+```bash
+# See why a package is installed
+pnpm why <package>
+
+# List all peer dependency warnings
+pnpm install --reporter=append-only 2>&1 | grep -i peer
+
+# Check dependency tree
+pnpm list --depth=Infinity
+```
+
+## Best Practices
+
+1. **Enable auto-install-peers** for convenience (default in pnpm v8+)
+
+2. **Use peerDependencyRules** instead of ignoring all warnings
+
+3. **Document suppressed warnings** explaining why they're safe
+
+4. **Keep peer deps ranges wide** in libraries:
+   ```json
+   {
+     "peerDependencies": {
+       "react": "^17.0.0 || ^18.0.0"
+     }
+   }
+   ```
+
+5. **Test with different peer versions** if you support multiple majors
+
+<!-- 
+Source references:
+- https://pnpm.io/package_json#pnpmpeerdependencyrules
+- https://pnpm.io/npmrc#auto-install-peers
+-->

.agents/skills/unocss/GENERATION.md

@@ -0,0 +1,5 @@
+# Generation Info
+
+- **Source:** `sources/unocss`
+- **Git SHA:** `2f7f267d0cc0c43d44357208aabb35b049359a08`
+- **Generated:** 2026-01-28

.agents/skills/unocss/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: unocss
+description: UnoCSS instant atomic CSS engine, superset of Tailwind CSS. Use when configuring UnoCSS, writing utility rules, shortcuts, or working with presets like Wind, Icons, Attributify.
+metadata:
+  author: Anthony Fu
+  version: "2026.1.28"
+  source: Generated from https://github.com/unocss/unocss, scripts located at https://github.com/antfu/skills
+---
+
+UnoCSS is an instant atomic CSS engine designed to be flexible and extensible. The core is un-opinionated - all CSS utilities are provided via presets. It's a superset of Tailwind CSS, so you can reuse your Tailwind knowledge for basic syntax usage.
+
+**Important:** Before writing UnoCSS code, agents should check for `uno.config.*` or `unocss.config.*` files in the project root to understand what presets, rules, and shortcuts are available. If the project setup is unclear, avoid using attributify mode and other advanced features - stick to basic `class` usage.
+
+> The skill is based on UnoCSS 66.x, generated at 2026-01-28.
+
+## Core
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Configuration | Config file setup and all configuration options | [core-config](references/core-config.md) |
+| Rules | Static and dynamic rules for generating CSS utilities | [core-rules](references/core-rules.md) |
+| Shortcuts | Combine multiple rules into single shorthands | [core-shortcuts](references/core-shortcuts.md) |
+| Theme | Theming system for colors, breakpoints, and design tokens | [core-theme](references/core-theme.md) |
+| Variants | Apply variations like hover:, dark:, responsive to rules | [core-variants](references/core-variants.md) |
+| Extracting | How UnoCSS extracts utilities from source code | [core-extracting](references/core-extracting.md) |
+| Safelist & Blocklist | Force include or exclude specific utilities | [core-safelist](references/core-safelist.md) |
+| Layers & Preflights | CSS layer ordering and raw CSS injection | [core-layers](references/core-layers.md) |
+
+## Presets
+
+### Main Presets
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Preset Wind3 | Tailwind CSS v3 / Windi CSS compatible preset (most common) | [preset-wind3](references/preset-wind3.md) |
+| Preset Wind4 | Tailwind CSS v4 compatible preset with modern CSS features | [preset-wind4](references/preset-wind4.md) |
+| Preset Mini | Minimal preset with essential utilities for custom builds | [preset-mini](references/preset-mini.md) |
+
+### Feature Presets
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Preset Icons | Pure CSS icons using Iconify with any icon set | [preset-icons](references/preset-icons.md) |
+| Preset Attributify | Group utilities in HTML attributes instead of class | [preset-attributify](references/preset-attributify.md) |
+| Preset Typography | Prose classes for typographic defaults | [preset-typography](references/preset-typography.md) |
+| Preset Web Fonts | Easy Google Fonts and other web fonts integration | [preset-web-fonts](references/preset-web-fonts.md) |
+| Preset Tagify | Use utilities as HTML tag names | [preset-tagify](references/preset-tagify.md) |
+| Preset Rem to Px | Convert rem units to px for utilities | [preset-rem-to-px](references/preset-rem-to-px.md) |
+
+## Transformers
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Variant Group | Shorthand for grouping utilities with common prefixes | [transformer-variant-group](references/transformer-variant-group.md) |
+| Directives | CSS directives: @apply, @screen, theme(), icon() | [transformer-directives](references/transformer-directives.md) |
+| Compile Class | Compile multiple classes into one hashed class | [transformer-compile-class](references/transformer-compile-class.md) |
+| Attributify JSX | Support valueless attributify in JSX/TSX | [transformer-attributify-jsx](references/transformer-attributify-jsx.md) |
+
+## Integrations
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Vite Integration | Setting up UnoCSS with Vite and framework-specific tips | [integrations-vite](references/integrations-vite.md) |
+| Nuxt Integration | UnoCSS module for Nuxt applications | [integrations-nuxt](references/integrations-nuxt.md) |

.agents/skills/unocss/references/core-config.md

@@ -0,0 +1,187 @@
+---
+name: unocss-configuration
+description: Config file setup and all configuration options for UnoCSS
+---
+
+# UnoCSS Configuration
+
+UnoCSS is configured via a dedicated config file in your project root.
+
+## Config File
+
+**Recommended:** Use a dedicated `uno.config.ts` file for best IDE support and HMR.
+
+```ts
+// uno.config.ts
+import {
+  defineConfig,
+  presetAttributify,
+  presetIcons,
+  presetTypography,
+  presetWebFonts,
+  presetWind3,
+  transformerDirectives,
+  transformerVariantGroup
+} from 'unocss'
+
+export default defineConfig({
+  shortcuts: [
+    // ...
+  ],
+  theme: {
+    colors: {
+      // ...
+    }
+  },
+  presets: [
+    presetWind3(),
+    presetAttributify(),
+    presetIcons(),
+    presetTypography(),
+    presetWebFonts({
+      fonts: {
+        // ...
+      },
+    }),
+  ],
+  transformers: [
+    transformerDirectives(),
+    transformerVariantGroup(),
+  ],
+})
+```
+
+UnoCSS automatically looks for `uno.config.{js,ts,mjs,mts}` or `unocss.config.{js,ts,mjs,mts}` in the project root.
+
+## Key Configuration Options
+
+### rules
+Define CSS utility rules. Later entries have higher priority.
+
+```ts
+rules: [
+  ['m-1', { margin: '0.25rem' }],
+  [/^m-(\d+)$/, ([, d]) => ({ margin: `${d / 4}rem` })],
+]
+```
+
+### shortcuts
+Combine multiple rules into a single shorthand.
+
+```ts
+shortcuts: {
+  'btn': 'py-2 px-4 font-semibold rounded-lg shadow-md',
+}
+```
+
+### theme
+Theme object for design tokens shared between rules.
+
+```ts
+theme: {
+  colors: {
+    brand: '#942192',
+  },
+  breakpoints: {
+    sm: '640px',
+    md: '768px',
+  },
+}
+```
+
+### presets
+Predefined configurations bundling rules, variants, and themes.
+
+```ts
+presets: [
+  presetWind3(),
+  presetIcons(),
+]
+```
+
+### transformers
+Transform source code to support special syntax.
+
+```ts
+transformers: [
+  transformerDirectives(),
+  transformerVariantGroup(),
+]
+```
+
+### variants
+Preprocess selectors with ability to rewrite CSS output.
+
+### extractors
+Handle source files and extract utility class names.
+
+### preflights
+Inject raw CSS globally.
+
+### layers
+Control the order of CSS layers. Default is `0`.
+
+```ts
+layers: {
+  'components': -1,
+  'default': 1,
+  'utilities': 2,
+}
+```
+
+### safelist
+Utilities that are always included in output.
+
+```ts
+safelist: ['p-1', 'p-2', 'p-3']
+```
+
+### blocklist
+Utilities that are always excluded.
+
+```ts
+blocklist: ['p-1', /^p-[2-4]$/]
+```
+
+### content
+Configure where to extract utilities from.
+
+```ts
+content: {
+  pipeline: {
+    include: [/\.(vue|svelte|tsx|html)($|\?)/],
+  },
+  filesystem: ['src/**/*.php'],
+}
+```
+
+### separators
+Variant separator characters. Default: `[':', '-']`
+
+### outputToCssLayers
+Output UnoCSS layers as CSS Cascade Layers.
+
+```ts
+outputToCssLayers: true
+```
+
+## Specifying Config File Location
+
+```ts
+// vite.config.ts
+import UnoCSS from 'unocss/vite'
+
+export default defineConfig({
+  plugins: [
+    UnoCSS({
+      configFile: '../my-uno.config.ts',
+    }),
+  ],
+})
+```
+
+<!-- 
+Source references:
+- https://unocss.dev/guide/config-file
+- https://unocss.dev/config/
+-->

.agents/skills/unocss/references/core-extracting.md

@@ -0,0 +1,137 @@
+---
+name: unocss-extracting
+description: How UnoCSS extracts utilities from source code
+---
+
+# Extracting
+
+UnoCSS searches for utility usages in your codebase and generates CSS on-demand.
+
+## Content Sources
+
+### Pipeline Extraction (Vite/Webpack)
+
+Most efficient - extracts from build tool pipeline.
+
+**Default file types:** `.jsx`, `.tsx`, `.vue`, `.md`, `.html`, `.svelte`, `.astro`, `.marko`
+
+**Not included by default:** `.js`, `.ts`
+
+```ts
+export default defineConfig({
+  content: {
+    pipeline: {
+      include: [
+        /\.(vue|svelte|[jt]sx|mdx?|astro|html)($|\?)/,
+        'src/**/*.{js,ts}', // Add js/ts
+      ],
+    },
+  },
+})
+```
+
+### Filesystem Extraction
+
+For files not in build pipeline:
+
+```ts
+export default defineConfig({
+  content: {
+    filesystem: [
+      'src/**/*.php',
+      'public/*.html',
+    ],
+  },
+})
+```
+
+### Inline Text Extraction
+
+```ts
+export default defineConfig({
+  content: {
+    inline: [
+      '<div class="p-4 text-red">Some text</div>',
+      async () => (await fetch('https://example.com')).text(),
+    ],
+  },
+})
+```
+
+## Magic Comments
+
+### @unocss-include
+
+Force scan a file:
+
+```ts
+// @unocss-include
+export const classes = {
+  active: 'bg-primary text-white',
+}
+```
+
+### @unocss-ignore
+
+Skip entire file:
+
+```ts
+// @unocss-ignore
+```
+
+### @unocss-skip-start / @unocss-skip-end
+
+Skip specific blocks:
+
+```html
+<p class="text-green">Extracted</p>
+<!-- @unocss-skip-start -->
+<p class="text-red">NOT extracted</p>
+<!-- @unocss-skip-end -->
+```
+
+## Limitations
+
+UnoCSS works at **build time** - dynamic classes don't work:
+
+```html
+<!-- Won't work! -->
+<div class="p-${size}"></div>
+```
+
+### Solutions
+
+**1. Safelist** - Pre-generate known values:
+
+```ts
+safelist: ['p-1', 'p-2', 'p-3', 'p-4']
+```
+
+**2. Static mapping** - List combinations statically:
+
+```ts
+const colors = {
+  red: 'text-red border-red',
+  blue: 'text-blue border-blue',
+}
+```
+
+**3. Runtime** - Use `@unocss/runtime` for true runtime generation.
+
+## Custom Extractors
+
+```ts
+extractors: [
+  {
+    name: 'my-extractor',
+    extract({ code }) {
+      return code.match(/class:[\w-]+/g) || []
+    },
+  },
+]
+```
+
+<!-- 
+Source references:
+- https://unocss.dev/guide/extracting
+-->

.agents/skills/unocss/references/core-layers.md

@@ -0,0 +1,104 @@
+---
+name: unocss-layers-preflights
+description: CSS layer ordering and raw CSS injection
+---
+
+# Layers and Preflights
+
+Control CSS output order and inject global CSS.
+
+## Layers
+
+Set layer on rules:
+
+```ts
+rules: [
+  [/^m-(\d)$/, ([, d]) => ({ margin: `${d / 4}rem` }), { layer: 'utilities' }],
+  ['btn', { padding: '4px' }], // default layer
+]
+```
+
+### Layer Ordering
+
+```ts
+layers: {
+  'components': -1,
+  'default': 1,
+  'utilities': 2,
+}
+```
+
+### Import Layers Separately
+
+```ts
+import 'uno:components.css'
+import 'uno.css'
+import './my-custom.css'
+import 'uno:utilities.css'
+```
+
+### CSS Cascade Layers
+
+```ts
+outputToCssLayers: true
+
+// Or with custom names
+outputToCssLayers: {
+  cssLayerName: (layer) => {
+    if (layer === 'default') return 'utilities'
+    if (layer === 'shortcuts') return 'utilities.shortcuts'
+  }
+}
+```
+
+## Layer Variants
+
+```html
+<!-- UnoCSS layer -->
+<p class="uno-layer-my-layer:text-xl">
+
+<!-- CSS @layer -->
+<p class="layer-my-layer:text-xl">
+```
+
+## Preflights
+
+Inject raw CSS globally:
+
+```ts
+preflights: [
+  {
+    getCSS: ({ theme }) => `
+      * {
+        color: ${theme.colors.gray?.[700] ?? '#333'};
+        margin: 0;
+      }
+    `,
+  },
+]
+```
+
+With layer:
+
+```ts
+preflights: [
+  {
+    layer: 'base',
+    getCSS: () => `html { font-family: system-ui; }`,
+  },
+]
+```
+
+## preset-wind4 Layers
+
+| Layer | Description | Order |
+|-------|-------------|-------|
+| `properties` | CSS @property rules | -200 |
+| `theme` | Theme CSS variables | -150 |
+| `base` | Reset styles | -100 |
+
+<!-- 
+Source references:
+- https://unocss.dev/config/layers
+- https://unocss.dev/config/preflights
+-->

.agents/skills/unocss/references/core-rules.md

@@ -0,0 +1,166 @@
+---
+name: unocss-rules
+description: Static and dynamic rules for generating CSS utilities in UnoCSS
+---
+
+# UnoCSS Rules
+
+Rules define utility classes and the CSS they generate. UnoCSS has many built-in rules via presets and allows custom rules.
+
+## Static Rules
+
+Simple mapping from class name to CSS properties:
+
+```ts
+rules: [
+  ['m-1', { margin: '0.25rem' }],
+  ['font-bold', { 'font-weight': 700 }],
+]
+```
+
+Usage: `<div class="m-1">` generates `.m-1 { margin: 0.25rem; }`
+
+**Note:** Use CSS property syntax with hyphens (e.g., `font-weight` not `fontWeight`). Quote properties with hyphens.
+
+## Dynamic Rules
+
+Use RegExp matcher with function body for flexible utilities:
+
+```ts
+rules: [
+  // Match m-1, m-2, m-100, etc.
+  [/^m-(\d+)$/, ([, d]) => ({ margin: `${d / 4}rem` })],
+  
+  // Access theme and context
+  [/^p-(\d+)$/, (match, ctx) => ({ padding: `${match[1] / 4}rem` })],
+]
+```
+
+The function receives:
+1. RegExp match result (destructure to get captured groups)
+2. Context object with `theme`, `symbols`, etc.
+
+## CSS Fallback Values
+
+Return 2D array for CSS property fallbacks (browser compatibility):
+
+```ts
+rules: [
+  [/^h-(\d+)dvh$/, ([_, d]) => [
+    ['height', `${d}vh`],
+    ['height', `${d}dvh`],
+  ]],
+]
+```
+
+Generates: `.h-100dvh { height: 100vh; height: 100dvh; }`
+
+## Special Symbols
+
+Control CSS output with symbols from `@unocss/core`:
+
+```ts
+import { symbols } from '@unocss/core'
+
+rules: [
+  ['grid', {
+    [symbols.parent]: '@supports (display: grid)',
+    display: 'grid',
+  }],
+]
+```
+
+### Available Symbols
+
+| Symbol | Description |
+|--------|-------------|
+| `symbols.parent` | Parent wrapper (e.g., `@supports`, `@media`) |
+| `symbols.selector` | Function to modify the selector |
+| `symbols.layer` | Set the UnoCSS layer |
+| `symbols.variants` | Array of variant handlers |
+| `symbols.shortcutsNoMerge` | Disable merging in shortcuts |
+| `symbols.noMerge` | Disable rule merging |
+| `symbols.sort` | Override sorting order |
+| `symbols.body` | Full control of CSS body |
+
+## Multi-Selector Rules
+
+Use generator functions to yield multiple CSS rules:
+
+```ts
+rules: [
+  [/^button-(.*)$/, function* ([, color], { symbols }) {
+    yield { background: color }
+    yield {
+      [symbols.selector]: selector => `${selector}:hover`,
+      background: `color-mix(in srgb, ${color} 90%, black)`
+    }
+  }],
+]
+```
+
+Generates both `.button-red { background: red; }` and `.button-red:hover { ... }`
+
+## Fully Controlled Rules
+
+Return a string for complete CSS control (advanced):
+
+```ts
+import { defineConfig, toEscapedSelector as e } from 'unocss'
+
+rules: [
+  [/^custom-(.+)$/, ([, name], { rawSelector, theme }) => {
+    const selector = e(rawSelector)
+    return `
+${selector} { font-size: ${theme.fontSize.sm}; }
+${selector}::after { content: 'after'; }
+@media (min-width: ${theme.breakpoints.sm}) {
+  ${selector} { font-size: ${theme.fontSize.lg}; }
+}
+`
+  }],
+]
+```
+
+**Warning:** Fully controlled rules don't work with variants like `hover:`.
+
+## Symbols.body for Variant Support
+
+Use `symbols.body` to keep variant support with custom CSS:
+
+```ts
+rules: [
+  ['custom-red', {
+    [symbols.body]: `
+      font-size: 1rem;
+      &::after { content: 'after'; }
+      & > .bar { color: red; }
+    `,
+    [symbols.selector]: selector => `:is(${selector})`,
+  }]
+]
+```
+
+## Rule Ordering
+
+Later rules have higher priority. Dynamic rules output is sorted alphabetically within the group.
+
+## Rule Merging
+
+UnoCSS merges rules with identical CSS bodies:
+
+```html
+<div class="m-2 hover:m2">
+```
+
+Generates:
+```css
+.hover\:m2:hover, .m-2 { margin: 0.5rem; }
+```
+
+Use `symbols.noMerge` to disable.
+
+<!-- 
+Source references:
+- https://unocss.dev/config/rules
+-->

.agents/skills/unocss/references/core-safelist.md

@@ -0,0 +1,105 @@
+---
+name: unocss-safelist-blocklist
+description: Force include or exclude specific utilities
+---
+
+# Safelist and Blocklist
+
+Control which utilities are always included or excluded.
+
+## Safelist
+
+Utilities always included, regardless of detection:
+
+```ts
+export default defineConfig({
+  safelist: [
+    'p-1', 'p-2', 'p-3',
+    // Dynamic generation
+    ...Array.from({ length: 4 }, (_, i) => `p-${i + 1}`),
+  ],
+})
+```
+
+### Function Form
+
+```ts
+safelist: [
+  'p-1',
+  () => ['m-1', 'm-2'],
+  (context) => {
+    const colors = Object.keys(context.theme.colors || {})
+    return colors.map(c => `bg-${c}-500`)
+  },
+]
+```
+
+### Common Use Cases
+
+```ts
+safelist: [
+  // Dynamic colors from CMS
+  () => ['primary', 'secondary'].flatMap(c => [
+    `bg-${c}`, `text-${c}`, `border-${c}`,
+  ]),
+  
+  // Component variants
+  () => {
+    const variants = ['primary', 'danger']
+    const sizes = ['sm', 'md', 'lg']
+    return variants.flatMap(v => sizes.map(s => `btn-${v}-${s}`))
+  },
+]
+```
+
+## Blocklist
+
+Utilities never generated:
+
+```ts
+blocklist: [
+  'p-1',           // Exact match
+  /^p-[2-4]$/,     // Regex
+]
+```
+
+### With Messages
+
+```ts
+blocklist: [
+  ['bg-red-500', { message: 'Use bg-red-600 instead' }],
+  [/^text-xs$/, { message: 'Use text-sm for accessibility' }],
+]
+```
+
+## Safelist vs Blocklist
+
+| Feature | Safelist | Blocklist |
+|---------|----------|-----------|
+| Purpose | Always include | Always exclude |
+| Strings | ✅ | ✅ |
+| Regex | ❌ | ✅ |
+| Functions | ✅ | ❌ |
+
+**Note:** Blocklist wins if utility is in both.
+
+## Best Practice
+
+Prefer static mappings over safelist:
+
+```ts
+// Better: UnoCSS extracts automatically
+const sizes = {
+  sm: 'text-sm p-2',
+  md: 'text-base p-4',
+}
+
+// Avoid: Large safelist
+safelist: ['text-sm', 'text-base', 'p-2', 'p-4']
+```
+
+<!-- 
+Source references:
+- https://unocss.dev/config/safelist
+- https://unocss.dev/guide/extracting
+-->

.agents/skills/unocss/references/core-shortcuts.md

@@ -0,0 +1,89 @@
+---
+name: unocss-shortcuts
+description: Combine multiple utility rules into single shorthand classes
+---
+
+# UnoCSS Shortcuts
+
+Shortcuts combine multiple rules into a single shorthand, inspired by Windi CSS.
+
+## Static Shortcuts
+
+Define as an object mapping shortcut names to utility combinations:
+
+```ts
+shortcuts: {
+  // Multiple utilities combined
+  'btn': 'py-2 px-4 font-semibold rounded-lg shadow-md',
+  'btn-green': 'text-white bg-green-500 hover:bg-green-700',
+  // Single utility alias
+  'red': 'text-red-100',
+}
+```
+
+Usage:
+```html
+<button class="btn btn-green">Click me</button>
+```
+
+## Dynamic Shortcuts
+
+Use RegExp matcher with function, similar to dynamic rules:
+
+```ts
+shortcuts: [
+  // Static shortcuts can be in array too
+  {
+    btn: 'py-2 px-4 font-semibold rounded-lg shadow-md',
+  },
+  // Dynamic shortcut
+  [/^btn-(.*)$/, ([, c]) => `bg-${c}-400 text-${c}-100 py-2 px-4 rounded-lg`],
+]
+```
+
+Now `btn-green` and `btn-red` generate:
+
+```css
+.btn-green {
+  padding: 0.5rem 1rem;
+  --un-bg-opacity: 1;
+  background-color: rgb(74 222 128 / var(--un-bg-opacity));
+  border-radius: 0.5rem;
+  --un-text-opacity: 1;
+  color: rgb(220 252 231 / var(--un-text-opacity));
+}
+```
+
+## Accessing Theme in Shortcuts
+
+Dynamic shortcuts receive context with theme access:
+
+```ts
+shortcuts: [
+  [/^badge-(.*)$/, ([, c], { theme }) => {
+    if (Object.keys(theme.colors).includes(c))
+      return `bg-${c}4:10 text-${c}5 rounded`
+  }],
+]
+```
+
+## Shortcuts Layer
+
+Shortcuts are output to the `shortcuts` layer by default. Configure with:
+
+```ts
+shortcutsLayer: 'my-shortcuts-layer'
+```
+
+## Key Points
+
+- Later shortcuts have higher priority
+- Shortcuts can reference other shortcuts
+- Dynamic shortcuts work like dynamic rules
+- Shortcuts are expanded at build time, not runtime
+- All variants work with shortcuts (`hover:btn`, `dark:btn`, etc.)
+
+<!-- 
+Source references:
+- https://unocss.dev/config/shortcuts
+-->

.agents/skills/unocss/references/core-theme.md

@@ -0,0 +1,172 @@
+---
+name: unocss-theme
+description: Theming system for colors, breakpoints, and design tokens
+---
+
+# UnoCSS Theme
+
+UnoCSS supports theming similar to Tailwind CSS / Windi CSS. The `theme` property is deep-merged with the default theme.
+
+## Basic Usage
+
+```ts
+theme: {
+  colors: {
+    veryCool: '#0000ff', // class="text-very-cool"
+    brand: {
+      primary: 'hsl(var(--hue, 217) 78% 51%)', // class="bg-brand-primary"
+      DEFAULT: '#942192' // class="bg-brand"
+    },
+  },
+}
+```
+
+## Using Theme in Rules
+
+Access theme values in dynamic rules:
+
+```ts
+rules: [
+  [/^text-(.*)$/, ([, c], { theme }) => {
+    if (theme.colors[c])
+      return { color: theme.colors[c] }
+  }],
+]
+```
+
+## Using Theme in Variants
+
+```ts
+variants: [
+  {
+    name: 'variant-name',
+    match(matcher, { theme }) {
+      // Access theme.breakpoints, theme.colors, etc.
+    },
+  },
+]
+```
+
+## Using Theme in Shortcuts
+
+```ts
+shortcuts: [
+  [/^badge-(.*)$/, ([, c], { theme }) => {
+    if (Object.keys(theme.colors).includes(c))
+      return `bg-${c}4:10 text-${c}5 rounded`
+  }],
+]
+```
+
+## Breakpoints
+
+**Warning:** Custom `breakpoints` object **overrides** the default, not merges.
+
+```ts
+theme: {
+  breakpoints: {
+    sm: '320px',
+    md: '640px',
+  },
+}
+```
+
+Only `sm:` and `md:` variants will be available.
+
+### Inherit Default Breakpoints
+
+Use `extendTheme` to merge with defaults:
+
+```ts
+extendTheme: (theme) => {
+  return {
+    ...theme,
+    breakpoints: {
+      ...theme.breakpoints,
+      sm: '320px',
+      md: '640px',
+    },
+  }
+}
+```
+
+**Note:** `verticalBreakpoints` works the same for vertical layout.
+
+### Breakpoint Sorting
+
+Breakpoints are sorted by size. Use consistent units to avoid errors:
+
+```ts
+theme: {
+  breakpoints: {
+    sm: '320px',
+    // Don't mix units - convert rem to px
+    // md: '40rem', // Bad
+    md: `${40 * 16}px`, // Good
+    lg: '960px',
+  },
+}
+```
+
+## ExtendTheme
+
+`extendTheme` lets you modify the merged theme object:
+
+### Mutate Theme
+
+```ts
+extendTheme: (theme) => {
+  theme.colors.veryCool = '#0000ff'
+  theme.colors.brand = {
+    primary: 'hsl(var(--hue, 217) 78% 51%)',
+  }
+}
+```
+
+### Replace Theme
+
+Return a new object to completely replace:
+
+```ts
+extendTheme: (theme) => {
+  return {
+    ...theme,
+    colors: {
+      ...theme.colors,
+      veryCool: '#0000ff',
+    },
+  }
+}
+```
+
+## Theme Differences in Presets
+
+### preset-wind3 vs preset-wind4
+
+| preset-wind3 | preset-wind4 |
+|--------------|--------------|
+| `fontFamily` | `font` |
+| `fontSize` | `text.fontSize` |
+| `lineHeight` | `text.lineHeight` or `leading` |
+| `letterSpacing` | `text.letterSpacing` or `tracking` |
+| `borderRadius` | `radius` |
+| `easing` | `ease` |
+| `breakpoints` | `breakpoint` |
+| `boxShadow` | `shadow` |
+| `transitionProperty` | `property` |
+
+## Common Theme Keys
+
+- `colors` - Color palette
+- `breakpoints` - Responsive breakpoints
+- `fontFamily` - Font stacks
+- `fontSize` - Text sizes
+- `spacing` - Spacing scale
+- `borderRadius` - Border radius values
+- `boxShadow` - Shadow definitions
+- `animation` - Animation keyframes and timing
+
+<!-- 
+Source references:
+- https://unocss.dev/config/theme
+-->

.agents/skills/unocss/references/core-variants.md

@@ -0,0 +1,175 @@
+---
+name: unocss-variants
+description: Apply variations like hover:, dark:, responsive to rules
+---
+
+# UnoCSS Variants
+
+Variants apply modifications to utility rules, like `hover:`, `dark:`, or responsive prefixes.
+
+## How Variants Work
+
+When matching `hover:m-2`:
+
+1. `hover:m-2` is extracted from source
+2. Sent to all variants for matching
+3. `hover:` variant matches and returns `m-2`
+4. Result `m-2` continues to next variants
+5. Finally matches the rule `.m-2 { margin: 0.5rem; }`
+6. Variant transformation applied: `.hover\:m-2:hover { margin: 0.5rem; }`
+
+## Creating Custom Variants
+
+```ts
+variants: [
+  // hover: variant
+  (matcher) => {
+    if (!matcher.startsWith('hover:'))
+      return matcher
+    return {
+      // Remove prefix, pass to next variants/rules
+      matcher: matcher.slice(6),
+      // Modify the selector
+      selector: s => `${s}:hover`,
+    }
+  },
+],
+rules: [
+  [/^m-(\d)$/, ([, d]) => ({ margin: `${d / 4}rem` })],
+]
+```
+
+## Variant Return Object
+
+- `matcher` - The processed class name to pass forward
+- `selector` - Function to customize the CSS selector
+- `parent` - Wrapper like `@media`, `@supports`
+- `layer` - Specify output layer
+- `sort` - Control ordering
+
+## Built-in Variants (preset-wind3)
+
+### Pseudo-classes
+- `hover:`, `focus:`, `active:`, `visited:`
+- `first:`, `last:`, `odd:`, `even:`
+- `disabled:`, `checked:`, `required:`
+- `focus-within:`, `focus-visible:`
+
+### Pseudo-elements
+- `before:`, `after:`
+- `placeholder:`, `selection:`
+- `marker:`, `file:`
+
+### Responsive
+- `sm:`, `md:`, `lg:`, `xl:`, `2xl:`
+- `lt-sm:` (less than sm)
+- `at-lg:` (at lg only)
+
+### Dark Mode
+- `dark:` - Class-based dark mode (default)
+- `@dark:` - Media query dark mode
+
+### Group/Peer
+- `group-hover:`, `group-focus:`
+- `peer-checked:`, `peer-focus:`
+
+### Container Queries
+- `@container`, `@sm:`, `@md:`
+
+### Print
+- `print:`
+
+### Supports
+- `supports-[display:grid]:`
+
+### Aria
+- `aria-checked:`, `aria-disabled:`
+
+### Data Attributes
+- `data-[state=open]:`
+
+## Dark Mode Configuration
+
+### Class-based (default)
+```ts
+presetWind3({
+  dark: 'class'
+})
+```
+
+```html
+<div class="dark:bg-gray-800">
+```
+
+Generates: `.dark .dark\:bg-gray-800 { ... }`
+
+### Media Query
+```ts
+presetWind3({
+  dark: 'media'
+})
+```
+
+Generates: `@media (prefers-color-scheme: dark) { ... }`
+
+### Opt-in Media Query
+Use `@dark:` regardless of config:
+
+```html
+<div class="@dark:bg-gray-800">
+```
+
+### Custom Selectors
+```ts
+presetWind3({
+  dark: {
+    light: '.light-mode',
+    dark: '.dark-mode',
+  }
+})
+```
+
+## CSS @layer Variant
+
+Native CSS `@layer` support:
+
+```html
+<div class="layer-foo:p-4" />
+```
+
+Generates:
+```css
+@layer foo {
+  .layer-foo\:p-4 { padding: 1rem; }
+}
+```
+
+## Breakpoint Differences from Windi CSS
+
+| Windi CSS | UnoCSS |
+|-----------|--------|
+| `<sm:p-1` | `lt-sm:p-1` |
+| `@lg:p-1` | `at-lg:p-1` |
+| `>xl:p-1` | `xl:p-1` |
+
+## Media Hover (Experimental)
+
+Addresses sticky hover on touch devices:
+
+```html
+<div class="@hover-text-red">
+```
+
+Generates:
+```css
+@media (hover: hover) and (pointer: fine) {
+  .\@hover-text-red:hover { color: rgb(248 113 113); }
+}
+```
+
+<!-- 
+Source references:
+- https://unocss.dev/config/variants
+- https://unocss.dev/presets/wind3
+- https://unocss.dev/presets/mini
+-->

.agents/skills/unocss/references/integrations-nuxt.md

@@ -0,0 +1,199 @@
+---
+name: unocss-nuxt-integration
+description: UnoCSS module for Nuxt applications
+---
+
+# UnoCSS Nuxt Integration
+
+The official Nuxt module for UnoCSS.
+
+## Installation
+
+```bash
+pnpm add -D unocss @unocss/nuxt
+```
+
+Add to Nuxt config:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: [
+    '@unocss/nuxt',
+  ],
+})
+```
+
+Create config file:
+
+```ts
+// uno.config.ts
+import { defineConfig, presetWind3 } from 'unocss'
+
+export default defineConfig({
+  presets: [
+    presetWind3(),
+  ],
+})
+```
+
+**Note:** The `uno.css` entry is automatically injected by the module.
+
+## Support Status
+
+| Build Tool | Nuxt 2 | Nuxt Bridge | Nuxt 3 |
+|------------|--------|-------------|--------|
+| Webpack Dev | ✅ | ✅ | 🚧 |
+| Webpack Build | ✅ | ✅ | ✅ |
+| Vite Dev | - | ✅ | ✅ |
+| Vite Build | - | ✅ | ✅ |
+
+## Configuration
+
+### Using uno.config.ts (Recommended)
+
+Use a dedicated config file for best IDE support:
+
+```ts
+// uno.config.ts
+import { defineConfig, presetWind3, presetIcons } from 'unocss'
+
+export default defineConfig({
+  presets: [
+    presetWind3(),
+    presetIcons(),
+  ],
+  shortcuts: {
+    'btn': 'py-2 px-4 font-semibold rounded-lg',
+  },
+})
+```
+
+### Nuxt Layers Support
+
+Enable automatic config merging from Nuxt layers:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  unocss: {
+    nuxtLayers: true,
+  },
+})
+```
+
+Then in your root config:
+
+```ts
+// uno.config.ts
+import config from './.nuxt/uno.config.mjs'
+
+export default config
+```
+
+Or extend the merged config:
+
+```ts
+// uno.config.ts
+import { mergeConfigs } from '@unocss/core'
+import config from './.nuxt/uno.config.mjs'
+
+export default mergeConfigs([config, {
+  // Your overrides
+  shortcuts: {
+    'custom': 'text-red-500',
+  },
+}])
+```
+
+## Common Setup Example
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: [
+    '@unocss/nuxt',
+  ],
+})
+```
+
+```ts
+// uno.config.ts
+import {
+  defineConfig,
+  presetAttributify,
+  presetIcons,
+  presetTypography,
+  presetWebFonts,
+  presetWind3,
+  transformerDirectives,
+  transformerVariantGroup,
+} from 'unocss'
+
+export default defineConfig({
+  presets: [
+    presetWind3(),
+    presetAttributify(),
+    presetIcons({
+      scale: 1.2,
+    }),
+    presetTypography(),
+    presetWebFonts({
+      fonts: {
+        sans: 'DM Sans',
+        mono: 'DM Mono',
+      },
+    }),
+  ],
+  transformers: [
+    transformerDirectives(),
+    transformerVariantGroup(),
+  ],
+  shortcuts: [
+    ['btn', 'px-4 py-1 rounded inline-block bg-teal-600 text-white cursor-pointer hover:bg-teal-700 disabled:cursor-default disabled:bg-gray-600 disabled:opacity-50'],
+  ],
+})
+```
+
+## Usage in Components
+
+```vue
+<template>
+  <div class="p-4 text-center">
+    <h1 class="text-3xl font-bold text-blue-600">
+      Hello UnoCSS!
+    </h1>
+    <button class="btn mt-4">
+      Click me
+    </button>
+  </div>
+</template>
+```
+
+With attributify mode:
+
+```vue
+<template>
+  <div p="4" text="center">
+    <h1 text="3xl blue-600" font="bold">
+      Hello UnoCSS!
+    </h1>
+  </div>
+</template>
+```
+
+## Inspector
+
+In development, visit `/_nuxt/__unocss` to access the UnoCSS inspector.
+
+## Key Differences from Vite
+
+- No need to import `virtual:uno.css` - automatically injected
+- Config file discovery works the same
+- All Vite plugin features available
+- Nuxt layers config merging available
+
+<!-- 
+Source references:
+- https://unocss.dev/integrations/nuxt
+-->

.agents/skills/unocss/references/integrations-vite.md

@@ -0,0 +1,283 @@
+---
+name: unocss-vite-integration
+description: Setting up UnoCSS with Vite and framework-specific tips
+---
+
+# UnoCSS Vite Integration
+
+The Vite plugin is the most common way to use UnoCSS.
+
+## Installation
+
+```bash
+pnpm add -D unocss
+```
+
+```ts
+// vite.config.ts
+import UnoCSS from 'unocss/vite'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [
+    UnoCSS(),
+  ],
+})
+```
+
+Create config file:
+
+```ts
+// uno.config.ts
+import { defineConfig, presetWind3 } from 'unocss'
+
+export default defineConfig({
+  presets: [
+    presetWind3(),
+  ],
+})
+```
+
+Add to entry:
+
+```ts
+// main.ts
+import 'virtual:uno.css'
+```
+
+## Modes
+
+### global (default)
+
+Standard mode - generates global CSS injected via `uno.css` import.
+
+```ts
+import 'virtual:uno.css'
+```
+
+### vue-scoped
+
+Injects generated CSS into Vue SFC `<style scoped>`.
+
+```ts
+UnoCSS({
+  mode: 'vue-scoped',
+})
+```
+
+### shadow-dom
+
+For Web Components using Shadow DOM:
+
+```ts
+UnoCSS({
+  mode: 'shadow-dom',
+})
+```
+
+Add placeholder in component styles:
+
+```ts
+const template = document.createElement('template')
+template.innerHTML = `
+<style>
+  :host { ... }
+  @unocss-placeholder
+</style>
+<div class="m-1em">...</div>
+`
+```
+
+### per-module (experimental)
+
+Generates CSS per module with optional scoping.
+
+### dist-chunk (experimental)
+
+Generates CSS per chunk on build for MPA.
+
+## DevTools Support
+
+Edit classes directly in browser DevTools:
+
+```ts
+import 'virtual:uno.css'
+import 'virtual:unocss-devtools'
+```
+
+**Warning:** Uses MutationObserver to detect changes. Dynamic classes from scripts will also be included.
+
+## Framework-Specific Setup
+
+### React
+
+```ts
+// vite.config.ts
+import React from '@vitejs/plugin-react'
+import UnoCSS from 'unocss/vite'
+
+export default {
+  plugins: [
+    UnoCSS(), // Must be before React when using attributify
+    React(),
+  ],
+}
+```
+
+**Note:** Remove `tsc` from build script if using `@unocss/preset-attributify`.
+
+### Vue
+
+Works out of the box with `@vitejs/plugin-vue`.
+
+### Svelte
+
+```ts
+import { svelte } from '@sveltejs/vite-plugin-svelte'
+import extractorSvelte from '@unocss/extractor-svelte'
+import UnoCSS from 'unocss/vite'
+
+export default {
+  plugins: [
+    UnoCSS({
+      extractors: [extractorSvelte()],
+    }),
+    svelte(),
+  ],
+}
+```
+
+Supports `class:foo` and `class:foo={bar}` syntax.
+
+### SvelteKit
+
+Same as Svelte, use `sveltekit()` from `@sveltejs/kit/vite`.
+
+### Solid
+
+```ts
+import UnoCSS from 'unocss/vite'
+import solidPlugin from 'vite-plugin-solid'
+
+export default {
+  plugins: [
+    UnoCSS(),
+    solidPlugin(),
+  ],
+}
+```
+
+### Preact
+
+```ts
+import Preact from '@preact/preset-vite'
+import UnoCSS from 'unocss/vite'
+
+export default {
+  plugins: [
+    UnoCSS(),
+    Preact(),
+  ],
+}
+```
+
+### Elm
+
+```ts
+import Elm from 'vite-plugin-elm'
+import UnoCSS from 'unocss/vite'
+
+export default {
+  plugins: [
+    Elm(),
+    UnoCSS(),
+  ],
+}
+```
+
+### Web Components (Lit)
+
+```ts
+UnoCSS({
+  mode: 'shadow-dom',
+  shortcuts: [
+    { 'cool-blue': 'bg-blue-500 text-white' },
+  ],
+})
+```
+
+```ts
+// my-element.ts
+@customElement('my-element')
+export class MyElement extends LitElement {
+  static styles = css`
+    :host { ... }
+    @unocss-placeholder
+  `
+}
+```
+
+Supports `part-[<part-name>]:<utility>` for `::part` styling.
+
+## Inspector
+
+Visit `http://localhost:5173/__unocss` in dev mode to:
+
+- Inspect generated CSS rules
+- See applied classes per file
+- Test utilities in REPL
+
+## Legacy Browser Support
+
+With `@vitejs/plugin-legacy`:
+
+```ts
+import legacy from '@vitejs/plugin-legacy'
+import UnoCSS from 'unocss/vite'
+
+export default {
+  plugins: [
+    UnoCSS({
+      legacy: {
+        renderModernChunks: false,
+      },
+    }),
+    legacy({
+      targets: ['defaults', 'not IE 11'],
+      renderModernChunks: false,
+    }),
+  ],
+}
+```
+
+## VanillaJS / TypeScript
+
+By default, `.js` and `.ts` files are not extracted. Configure to include:
+
+```ts
+// uno.config.ts
+export default defineConfig({
+  content: {
+    pipeline: {
+      include: [
+        /\.(vue|svelte|[jt]sx|html)($|\?)/,
+        'src/**/*.{js,ts}',
+      ],
+    },
+  },
+})
+```
+
+Or use magic comment in files:
+
+```ts
+// @unocss-include
+export const classes = {
+  active: 'bg-primary text-white',
+}
+```
+
+<!-- 
+Source references:
+- https://unocss.dev/integrations/vite
+-->

.agents/skills/unocss/references/preset-attributify.md

@@ -0,0 +1,142 @@
+---
+name: preset-attributify
+description: Group utilities in HTML attributes instead of class
+---
+
+# Preset Attributify
+
+Group utilities in HTML attributes for better readability.
+
+## Installation
+
+```ts
+import { defineConfig, presetAttributify, presetWind3 } from 'unocss'
+
+export default defineConfig({
+  presets: [
+    presetWind3(),
+    presetAttributify(),
+  ],
+})
+```
+
+## Basic Usage
+
+Instead of long class strings:
+
+```html
+<button class="bg-blue-400 hover:bg-blue-500 text-sm text-white font-mono font-light py-2 px-4 rounded border-2 border-blue-200">
+  Button
+</button>
+```
+
+Group by prefix in attributes:
+
+```html
+<button
+  bg="blue-400 hover:blue-500"
+  text="sm white"
+  font="mono light"
+  p="y-2 x-4"
+  border="2 rounded blue-200"
+>
+  Button
+</button>
+```
+
+## Prefix Self-Referencing
+
+For utilities matching their prefix (`flex`, `grid`, `border`), use `~`:
+
+```html
+<!-- Before -->
+<button class="border border-red">Button</button>
+
+<!-- After -->
+<button border="~ red">Button</button>
+```
+
+## Valueless Attributify
+
+Use utilities as boolean attributes:
+
+```html
+<div m-2 rounded text-teal-400 />
+```
+
+## Handling Property Conflicts
+
+When attribute names conflict with HTML properties:
+
+```html
+<!-- Use un- prefix -->
+<a un-text="red">Text color to red</a>
+```
+
+### Enforce Prefix
+
+```ts
+presetAttributify({
+  prefix: 'un-',
+  prefixedOnly: true,
+})
+```
+
+## Options
+
+```ts
+presetAttributify({
+  strict: false,           // Only generate CSS for attributify
+  prefix: 'un-',           // Attribute prefix
+  prefixedOnly: false,     // Require prefix for all
+  nonValuedAttribute: true, // Support valueless attributes
+  ignoreAttributes: [],    // Attributes to ignore
+  trueToNonValued: false,  // Treat value="true" as valueless
+})
+```
+
+## TypeScript Support
+
+### Vue 3
+
+```ts
+// html.d.ts
+declare module '@vue/runtime-dom' {
+  interface HTMLAttributes { [key: string]: any }
+}
+declare module '@vue/runtime-core' {
+  interface AllowedComponentProps { [key: string]: any }
+}
+export {}
+```
+
+### React
+
+```ts
+import type { AttributifyAttributes } from '@unocss/preset-attributify'
+
+declare module 'react' {
+  interface HTMLAttributes<T> extends AttributifyAttributes {}
+}
+```
+
+## JSX Support
+
+For JSX where `<div foo>` becomes `<div foo={true}>`:
+
+```ts
+import { transformerAttributifyJsx } from 'unocss'
+
+export default defineConfig({
+  transformers: [
+    transformerAttributifyJsx(),
+  ],
+})
+```
+
+**Important:** Only use attributify if `uno.config.*` shows `presetAttributify()` is enabled.
+
+<!-- 
+Source references:
+- https://unocss.dev/presets/attributify
+-->

.agents/skills/unocss/references/preset-icons.md

@@ -0,0 +1,184 @@
+---
+name: preset-icons
+description: Pure CSS icons using Iconify with any icon set
+---
+
+# Preset Icons
+
+Use any icon as a pure CSS class, powered by Iconify.
+
+## Installation
+
+```bash
+pnpm add -D @unocss/preset-icons @iconify-json/[collection-name]
+```
+
+Example: `@iconify-json/mdi` for Material Design Icons, `@iconify-json/carbon` for Carbon icons.
+
+```ts
+import { defineConfig, presetIcons } from 'unocss'
+
+export default defineConfig({
+  presets: [
+    presetIcons(),
+  ],
+})
+```
+
+## Usage
+
+Two naming conventions:
+- `<prefix><collection>-<icon>` → `i-ph-anchor-simple-thin`
+- `<prefix><collection>:<icon>` → `i-ph:anchor-simple-thin`
+
+```html
+<!-- Phosphor anchor icon -->
+<div class="i-ph-anchor-simple-thin" />
+
+<!-- Material Design alarm with color -->
+<div class="i-mdi-alarm text-orange-400" />
+
+<!-- Large Vue logo -->
+<div class="i-logos-vue text-3xl" />
+
+<!-- Dynamic: Sun in light mode, Moon in dark -->
+<button class="i-carbon-sun dark:i-carbon-moon" />
+
+<!-- Hover effect -->
+<div class="i-twemoji-grinning-face-with-smiling-eyes hover:i-twemoji-face-with-tears-of-joy" />
+```
+
+Browse icons at [icones.js.org](https://icones.js.org/) or [Iconify](https://icon-sets.iconify.design/).
+
+## Icon Modes
+
+Icons automatically choose between `mask` (monochrome) and `background-img` (colorful).
+
+### Force Specific Mode
+
+- `?mask` - Render as mask (colorable with `currentColor`)
+- `?bg` - Render as background image (preserves original colors)
+
+```html
+<!-- Original with colors -->
+<div class="i-vscode-icons:file-type-light-pnpm" />
+
+<!-- Force mask mode, apply custom color -->
+<div class="i-vscode-icons:file-type-light-pnpm?mask text-red-300" />
+```
+
+## Options
+
+```ts
+presetIcons({
+  scale: 1.2,              // Scale relative to font size
+  prefix: 'i-',            // Class prefix (default)
+  mode: 'auto',            // 'auto' | 'mask' | 'bg'
+  extraProperties: {
+    'display': 'inline-block',
+    'vertical-align': 'middle',
+  },
+  warn: true,              // Warn on missing icons
+  autoInstall: true,       // Auto-install missing icon sets
+  cdn: 'https://esm.sh/',  // CDN for browser usage
+})
+```
+
+## Custom Icon Collections
+
+### Inline SVGs
+
+```ts
+presetIcons({
+  collections: {
+    custom: {
+      circle: '<svg viewBox="0 0 120 120"><circle cx="60" cy="60" r="50"></circle></svg>',
+    },
+  }
+})
+```
+
+Usage: `<span class="i-custom:circle"></span>`
+
+### File System Loader
+
+```ts
+import { FileSystemIconLoader } from '@iconify/utils/lib/loader/node-loaders'
+
+presetIcons({
+  collections: {
+    'my-icons': FileSystemIconLoader(
+      './assets/icons',
+      svg => svg.replace(/#fff/, 'currentColor')
+    ),
+  }
+})
+```
+
+### Dynamic Import (Browser)
+
+```ts
+import presetIcons from '@unocss/preset-icons/browser'
+
+presetIcons({
+  collections: {
+    carbon: () => import('@iconify-json/carbon/icons.json').then(i => i.default),
+  }
+})
+```
+
+## Icon Customization
+
+```ts
+presetIcons({
+  customizations: {
+    // Transform SVG
+    transform(svg, collection, icon) {
+      return svg.replace(/#fff/, 'currentColor')
+    },
+    // Global sizing
+    customize(props) {
+      props.width = '2em'
+      props.height = '2em'
+      return props
+    },
+    // Per-collection
+    iconCustomizer(collection, icon, props) {
+      if (collection === 'mdi') {
+        props.width = '2em'
+      }
+    }
+  }
+})
+```
+
+## CSS Directive
+
+Use `icon()` in CSS (requires transformer-directives):
+
+```css
+.icon {
+  background-image: icon('i-carbon-sun');
+}
+.icon-colored {
+  background-image: icon('i-carbon-moon', '#fff');
+}
+```
+
+## Accessibility
+
+```html
+<!-- With label -->
+<a href="/profile" aria-label="Profile" class="i-ph:user-duotone"></a>
+
+<!-- Decorative -->
+<a href="/profile">
+  <span aria-hidden="true" class="i-ph:user-duotone"></span>
+  My Profile
+</a>
+```
+
+<!-- 
+Source references:
+- https://unocss.dev/presets/icons
+-->

.agents/skills/unocss/references/preset-mini.md

@@ -0,0 +1,158 @@
+---
+name: preset-mini
+description: Minimal preset with essential utilities for UnoCSS
+---
+
+# Preset Mini
+
+The minimal preset with only essential rules and variants. Good starting point for custom presets.
+
+## Installation
+
+```ts
+import { defineConfig, presetMini } from 'unocss'
+
+export default defineConfig({
+  presets: [
+    presetMini(),
+  ],
+})
+```
+
+## What's Included
+
+Subset of `preset-wind3` with essential utilities aligned to CSS properties:
+
+- Basic spacing (margin, padding)
+- Display (flex, grid, block, etc.)
+- Positioning (absolute, relative, fixed)
+- Sizing (width, height)
+- Colors (text, background, border)
+- Typography basics (font-size, font-weight)
+- Borders and border-radius
+- Basic transforms and transitions
+
+## What's NOT Included
+
+Opinionated or complex Tailwind utilities:
+- `container`
+- Complex animations
+- Gradients
+- Advanced typography
+- Prose classes
+
+## Use Cases
+
+1. **Building custom presets** - Start with mini and add only what you need
+2. **Minimal bundle size** - When you only need basic utilities
+3. **Learning** - Understand UnoCSS core without Tailwind complexity
+
+## Dark Mode
+
+Same as preset-wind3:
+
+```ts
+presetMini({
+  dark: 'class' // or 'media'
+})
+```
+
+```html
+<div class="dark:bg-red:10" />
+```
+
+Class-based:
+```css
+.dark .dark\:bg-red\:10 {
+  background-color: rgb(248 113 113 / 0.1);
+}
+```
+
+Media query:
+```css
+@media (prefers-color-scheme: dark) {
+  .dark\:bg-red\:10 {
+    background-color: rgb(248 113 113 / 0.1);
+  }
+}
+```
+
+## CSS @layer Variant
+
+Native CSS layer support:
+
+```html
+<div class="layer-foo:p4" />
+```
+
+```css
+@layer foo {
+  .layer-foo\:p4 {
+    padding: 1rem;
+  }
+}
+```
+
+## Theme Customization
+
+```ts
+presetMini({
+  theme: {
+    colors: {
+      veryCool: '#0000ff',
+      brand: {
+        primary: 'hsl(var(--hue, 217) 78% 51%)',
+      }
+    },
+  }
+})
+```
+
+**Note:** `breakpoints` property is overridden, not merged.
+
+## Options
+
+```ts
+presetMini({
+  // Dark mode: 'class' | 'media' | { light: string, dark: string }
+  dark: 'class',
+  
+  // Generate [group=""] instead of .group for attributify
+  attributifyPseudo: false,
+  
+  // CSS variable prefix (default: 'un-')
+  variablePrefix: 'un-',
+  
+  // Utility prefix
+  prefix: undefined,
+  
+  // Preflight generation: true | false | 'on-demand'
+  preflight: true,
+})
+```
+
+## Building on Mini
+
+Create custom preset extending mini:
+
+```ts
+import { presetMini } from 'unocss'
+import type { Preset } from 'unocss'
+
+export const myPreset: Preset = {
+  name: 'my-preset',
+  presets: [presetMini()],
+  rules: [
+    // Add custom rules
+    ['card', { 'border-radius': '8px', 'box-shadow': '0 2px 8px rgba(0,0,0,0.1)' }],
+  ],
+  shortcuts: {
+    'btn': 'px-4 py-2 rounded bg-blue-500 text-white',
+  },
+}
+```
+
+<!-- 
+Source references:
+- https://unocss.dev/presets/mini
+-->

.agents/skills/unocss/references/preset-rem-to-px.md

@@ -0,0 +1,97 @@
+---
+name: preset-rem-to-px
+description: Convert rem units to px for utilities
+---
+
+# Preset Rem to Px
+
+Converts `rem` units to `px` in generated utilities.
+
+## Installation
+
+```ts
+import { defineConfig, presetRemToPx, presetWind3 } from 'unocss'
+
+export default defineConfig({
+  presets: [
+    presetWind3(),
+    presetRemToPx(),
+  ],
+})
+```
+
+## What It Does
+
+Transforms all rem values to px:
+
+```html
+<div class="p-4">
+```
+
+Without preset:
+```css
+.p-4 { padding: 1rem; }
+```
+
+With preset:
+```css
+.p-4 { padding: 16px; }
+```
+
+## Use Cases
+
+- Projects requiring pixel-perfect designs
+- Environments where rem doesn't work well
+- Consistency with pixel-based design systems
+- Email templates (better compatibility)
+
+## Options
+
+```ts
+presetRemToPx({
+  // Base font size for conversion (default: 16)
+  baseFontSize: 16,
+})
+```
+
+Custom base:
+
+```ts
+presetRemToPx({
+  baseFontSize: 14, // 1rem = 14px
+})
+```
+
+## With Preset Wind4
+
+**Note:** `presetRemToPx` is not needed with `preset-wind4`. Use the built-in processor instead:
+
+```ts
+import { createRemToPxProcessor } from '@unocss/preset-wind4/utils'
+
+export default defineConfig({
+  presets: [
+    presetWind4({
+      preflights: {
+        theme: {
+          process: createRemToPxProcessor(),
+        }
+      },
+    }),
+  ],
+  // Also apply to utilities
+  postprocess: [createRemToPxProcessor()],
+})
+```
+
+## Important Notes
+
+- Order matters: place after the preset that generates rem values
+- Affects all utilities with rem units
+- Theme values in rem are also converted
+
+<!-- 
+Source references:
+- https://unocss.dev/presets/rem-to-px
+- https://unocss.dev/presets/wind4
+-->

.agents/skills/unocss/references/preset-tagify.md

@@ -0,0 +1,134 @@
+---
+name: preset-tagify
+description: Use utilities as HTML tag names
+---
+
+# Preset Tagify
+
+Use CSS utilities directly as HTML tag names.
+
+## Installation
+
+```ts
+import { defineConfig, presetTagify } from 'unocss'
+
+export default defineConfig({
+  presets: [
+    presetTagify(),
+  ],
+})
+```
+
+## Basic Usage
+
+Instead of:
+
+```html
+<span class="text-red">red text</span>
+<div class="flex">flexbox</div>
+<span class="i-line-md-emoji-grin"></span>
+```
+
+Use tag names directly:
+
+```html
+<text-red>red text</text-red>
+<flex>flexbox</flex>
+<i-line-md-emoji-grin />
+```
+
+Works exactly the same!
+
+## With Prefix
+
+```ts
+presetTagify({
+  prefix: 'un-'
+})
+```
+
+```html
+<!-- Matched -->
+<un-flex></un-flex>
+
+<!-- Not matched -->
+<flex></flex>
+```
+
+## Extra Properties
+
+Add CSS properties to matched tags:
+
+```ts
+presetTagify({
+  // Add display: inline-block to icons
+  extraProperties: matched => matched.startsWith('i-')
+    ? { display: 'inline-block' }
+    : {},
+})
+```
+
+Or apply to all:
+
+```ts
+presetTagify({
+  extraProperties: { display: 'block' }
+})
+```
+
+## Options
+
+```ts
+presetTagify({
+  // Tag prefix
+  prefix: '',
+  
+  // Excluded tags (won't be processed)
+  excludedTags: ['b', /^h\d+$/, 'table'],
+  
+  // Extra CSS properties
+  extraProperties: {},
+  
+  // Enable default extractor
+  defaultExtractor: true,
+})
+```
+
+## Excluded Tags
+
+By default, these tags are excluded:
+- `b` (bold)
+- `h1` through `h6` (headings)
+- `table`
+
+Add your own:
+
+```ts
+presetTagify({
+  excludedTags: [
+    'b',
+    /^h\d+$/,
+    'table',
+    'article',  // Add custom exclusions
+    /^my-/,     // Exclude tags starting with 'my-'
+  ],
+})
+```
+
+## Use Cases
+
+- Quick prototyping
+- Cleaner HTML for simple pages
+- Icon embedding: `<i-carbon-sun />`
+- Semantic-like styling: `<flex-center>`, `<text-red>`
+
+## Limitations
+
+- Custom element names must contain a hyphen (HTML spec)
+- Some frameworks may not support all custom elements
+- Utilities without hyphens need the prefix option
+
+<!-- 
+Source references:
+- https://unocss.dev/presets/tagify
+-->

.agents/skills/unocss/references/preset-typography.md

@@ -0,0 +1,95 @@
+---
+name: preset-typography
+description: Prose classes for typographic defaults on vanilla HTML content
+---
+
+# Preset Typography
+
+Prose classes for adding typographic defaults to vanilla HTML content.
+
+## Installation
+
+```ts
+import { defineConfig, presetTypography, presetWind3 } from 'unocss'
+
+export default defineConfig({
+  presets: [
+    presetWind3(), // Required!
+    presetTypography(),
+  ],
+})
+```
+
+## Basic Usage
+
+```html
+<article class="prose">
+  <h1>My Article</h1>
+  <p>This is styled with typographic defaults...</p>
+</article>
+```
+
+## Sizes
+
+```html
+<article class="prose prose-sm">Small</article>
+<article class="prose prose-base">Base (default)</article>
+<article class="prose prose-lg">Large</article>
+<article class="prose prose-xl">Extra large</article>
+<article class="prose prose-2xl">2X large</article>
+```
+
+Responsive:
+```html
+<article class="prose prose-sm md:prose-base lg:prose-lg">
+  Responsive typography
+</article>
+```
+
+## Colors
+
+```html
+<article class="prose prose-gray">Gray (default)</article>
+<article class="prose prose-slate">Slate</article>
+<article class="prose prose-blue">Blue</article>
+```
+
+## Dark Mode
+
+```html
+<article class="prose dark:prose-invert">
+  Dark mode typography
+</article>
+```
+
+## Excluding Elements
+
+```html
+<article class="prose">
+  <p>Styled</p>
+  <div class="not-prose">
+    <p>NOT styled</p>
+  </div>
+</article>
+```
+
+**Note:** `not-prose` only works as a class.
+
+## Options
+
+```ts
+presetTypography({
+  selectorName: 'prose',      // Custom selector
+  cssVarPrefix: '--un-prose', // CSS variable prefix
+  important: false,           // Make !important
+  cssExtend: {
+    'code': { color: '#8b5cf6' },
+    'a:hover': { color: '#f43f5e' },
+  },
+})
+```
+
+<!-- 
+Source references:
+- https://unocss.dev/presets/typography
+-->

.agents/skills/unocss/references/preset-web-fonts.md

@@ -0,0 +1,91 @@
+---
+name: preset-web-fonts
+description: Easy Google Fonts and other web fonts integration
+---
+
+# Preset Web Fonts
+
+Easily use web fonts from Google Fonts and other providers.
+
+## Installation
+
+```ts
+import { defineConfig, presetWebFonts, presetWind3 } from 'unocss'
+
+export default defineConfig({
+  presets: [
+    presetWind3(),
+    presetWebFonts({
+      provider: 'google',
+      fonts: {
+        sans: 'Roboto',
+        mono: 'Fira Code',
+      },
+    }),
+  ],
+})
+```
+
+## Providers
+
+- `google` - Google Fonts (default)
+- `bunny` - Privacy-friendly alternative
+- `fontshare` - Quality fonts by ITF
+- `fontsource` - Self-hosted open source fonts
+- `coollabs` - Privacy-friendly drop-in replacement
+- `none` - Treat as system font
+
+## Font Configuration
+
+```ts
+fonts: {
+  // Simple
+  sans: 'Roboto',
+  
+  // Multiple (fallback)
+  mono: ['Fira Code', 'Fira Mono:400,700'],
+  
+  // Detailed
+  lato: [
+    {
+      name: 'Lato',
+      weights: ['400', '700'],
+      italic: true,
+    },
+    {
+      name: 'sans-serif',
+      provider: 'none',
+    },
+  ],
+}
+```
+
+## Usage
+
+```html
+<p class="font-sans">Roboto</p>
+<code class="font-mono">Fira Code</code>
+```
+
+## Local Fonts
+
+Self-host fonts:
+
+```ts
+import { createLocalFontProcessor } from '@unocss/preset-web-fonts/local'
+
+presetWebFonts({
+  provider: 'none',
+  fonts: { sans: 'Roboto' },
+  processors: createLocalFontProcessor({
+    cacheDir: 'node_modules/.cache/unocss/fonts',
+    fontAssetsDir: 'public/assets/fonts',
+    fontServeBaseUrl: '/assets/fonts',
+  })
+})
+```
+
+<!-- 
+Source references:
+- https://unocss.dev/presets/web-fonts
+-->

.agents/skills/unocss/references/preset-wind3.md

@@ -0,0 +1,194 @@
+---
+name: preset-wind3
+description: Tailwind CSS / Windi CSS compatible preset for UnoCSS
+---
+
+# Preset Wind3
+
+The Tailwind CSS / Windi CSS compatible preset. Most commonly used preset for UnoCSS.
+
+## Installation
+
+```ts
+import { defineConfig, presetWind3 } from 'unocss'
+
+export default defineConfig({
+  presets: [
+    presetWind3(),
+  ],
+})
+```
+
+**Note:** `@unocss/preset-uno` and `@unocss/preset-wind` are deprecated and renamed to `@unocss/preset-wind3`.
+
+## Features
+
+- Full Tailwind CSS v3 compatibility
+- Dark mode (`dark:`, `@dark:`)
+- All responsive variants (`sm:`, `md:`, `lg:`, `xl:`, `2xl:`)
+- All standard utilities (flex, grid, spacing, colors, typography, etc.)
+- Animation support (includes Animate.css animations)
+
+## Dark Mode
+
+### Class-based (default)
+
+```html
+<div class="dark:bg-gray-800">
+```
+
+Generates: `.dark .dark\:bg-gray-800 { ... }`
+
+### Media Query Based
+
+```ts
+presetWind3({
+  dark: 'media'
+})
+```
+
+Generates: `@media (prefers-color-scheme: dark) { ... }`
+
+### Opt-in Media Query
+
+Use `@dark:` regardless of config:
+
+```html
+<div class="@dark:bg-gray-800">
+```
+
+## Options
+
+```ts
+presetWind3({
+  // Dark mode strategy
+  dark: 'class', // 'class' | 'media' | { light: '.light', dark: '.dark' }
+  
+  // Generate pseudo selector as [group=""] instead of .group
+  attributifyPseudo: false,
+  
+  // CSS custom properties prefix
+  variablePrefix: 'un-',
+  
+  // Utils prefix
+  prefix: '',
+  
+  // Generate preflight CSS
+  preflight: true, // true | false | 'on-demand'
+  
+  // Mark all utilities as !important
+  important: false, // boolean | string (selector)
+})
+```
+
+### Important Option
+
+Make all utilities `!important`:
+
+```ts
+presetWind3({
+  important: true,
+})
+```
+
+Or scope with selector to increase specificity without `!important`:
+
+```ts
+presetWind3({
+  important: '#app',
+})
+```
+
+Output: `#app :is(.dark .dark\:bg-blue) { ... }`
+
+## Differences from Tailwind CSS
+
+### Quotes Not Supported
+
+Template quotes don't work due to extractor:
+
+```html
+<!-- Won't work -->
+<div class="before:content-['']">
+
+<!-- Use shortcut instead -->
+<div class="before:content-empty">
+```
+
+### Background Position
+
+Use `position:` prefix for custom values:
+
+```html
+<!-- Tailwind -->
+<div class="bg-[center_top_1rem]">
+
+<!-- UnoCSS -->
+<div class="bg-[position:center_top_1rem]">
+```
+
+### Animations
+
+UnoCSS integrates Animate.css. Use `-alt` suffix for Animate.css versions when names conflict:
+
+- `animate-bounce` - Tailwind version
+- `animate-bounce-alt` - Animate.css version
+
+Custom animations:
+
+```ts
+theme: {
+  animation: {
+    keyframes: {
+      custom: '{0%, 100% { opacity: 0; } 50% { opacity: 1; }}',
+    },
+    durations: {
+      custom: '1s',
+    },
+    timingFns: {
+      custom: 'ease-in-out',
+    },
+    counts: {
+      custom: 'infinite',
+    },
+  }
+}
+```
+
+## Differences from Windi CSS
+
+| Windi CSS | UnoCSS |
+|-----------|--------|
+| `<sm:p-1` | `lt-sm:p-1` |
+| `@lg:p-1` | `at-lg:p-1` |
+| `>xl:p-1` | `xl:p-1` |
+
+Bracket syntax uses `_` instead of `,`:
+
+```html
+<!-- Windi CSS -->
+<div class="grid-cols-[1fr,10px,max-content]">
+
+<!-- UnoCSS -->
+<div class="grid-cols-[1fr_10px_max-content]">
+```
+
+## Experimental: Media Hover
+
+Addresses sticky hover on touch devices:
+
+```html
+<div class="@hover-text-red">
+```
+
+Generates:
+```css
+@media (hover: hover) and (pointer: fine) {
+  .\@hover-text-red:hover { ... }
+}
+```
+
+<!-- 
+Source references:
+- https://unocss.dev/presets/wind3
+-->

.agents/skills/unocss/references/preset-wind4.md

@@ -0,0 +1,247 @@
+---
+name: preset-wind4
+description: Tailwind CSS v4 compatible preset with enhanced features
+---
+
+# Preset Wind4
+
+The Tailwind CSS v4 compatible preset. Enhances preset-wind3 with modern CSS features.
+
+## Installation
+
+```ts
+import { defineConfig, presetWind4 } from 'unocss'
+
+export default defineConfig({
+  presets: [
+    presetWind4(),
+  ],
+})
+```
+
+## Key Differences from Wind3
+
+### Built-in CSS Reset
+
+No need for `@unocss/reset` - reset is built-in:
+
+```ts
+// Remove these imports
+import '@unocss/reset/tailwind.css' // ❌ Not needed
+import '@unocss/reset/tailwind-compat.css' // ❌ Not needed
+
+// Enable in config
+presetWind4({
+  preflights: {
+    reset: true,
+  },
+})
+```
+
+### OKLCH Color Model
+
+Uses `oklch` for better color perception and contrast. Not compatible with `presetLegacyCompat`.
+
+### Theme CSS Variables
+
+Automatically generates CSS variables from theme:
+
+```css
+:root, :host {
+  --spacing: 0.25rem;
+  --font-sans: ui-sans-serif, system-ui, sans-serif;
+  --colors-black: #000;
+  --colors-white: #fff;
+  /* ... */
+}
+```
+
+### @property CSS Rules
+
+Uses `@property` for better browser optimization:
+
+```css
+@property --un-text-opacity {
+  syntax: '<percentage>';
+  inherits: false;
+  initial-value: 100%;
+}
+```
+
+### Theme Key Changes
+
+| preset-wind3 | preset-wind4 |
+|--------------|--------------|
+| `fontFamily` | `font` |
+| `fontSize` | `text.fontSize` |
+| `lineHeight` | `text.lineHeight` or `leading` |
+| `letterSpacing` | `text.letterSpacing` or `tracking` |
+| `borderRadius` | `radius` |
+| `easing` | `ease` |
+| `breakpoints` | `breakpoint` |
+| `verticalBreakpoints` | `verticalBreakpoint` |
+| `boxShadow` | `shadow` |
+| `transitionProperty` | `property` |
+| `container.maxWidth` | `containers.maxWidth` |
+| Size properties (`width`, `height`, etc.) | Unified to `spacing` |
+
+## Options
+
+```ts
+presetWind4({
+  preflights: {
+    // Built-in reset styles
+    reset: true,
+    
+    // Theme CSS variables generation
+    theme: 'on-demand', // true | false | 'on-demand'
+    
+    // @property CSS rules
+    property: true,
+  },
+})
+```
+
+### Theme Variable Processing
+
+Convert rem to px for theme variables:
+
+```ts
+import { createRemToPxProcessor } from '@unocss/preset-wind4/utils'
+
+presetWind4({
+  preflights: {
+    theme: {
+      mode: 'on-demand',
+      process: createRemToPxProcessor(),
+    }
+  },
+})
+
+// Also apply to utilities
+export default defineConfig({
+  postprocess: [createRemToPxProcessor()],
+})
+```
+
+### Property Layer Customization
+
+```ts
+presetWind4({
+  preflights: {
+    property: {
+      // Custom parent wrapper
+      parent: '@layer custom-properties',
+      // Custom selector
+      selector: ':where(*, ::before, ::after)',
+    },
+  },
+})
+```
+
+Remove `@supports` wrapper:
+
+```ts
+presetWind4({
+  preflights: {
+    property: {
+      parent: false,
+    },
+  },
+})
+```
+
+## Generated Layers
+
+| Layer | Description | Order |
+|-------|-------------|-------|
+| `properties` | CSS `@property` rules | -200 |
+| `theme` | Theme CSS variables | -150 |
+| `base` | Reset/preflight styles | -100 |
+
+## Theme.defaults
+
+Global default configuration for reset styles:
+
+```ts
+import type { Theme } from '@unocss/preset-wind4/theme'
+
+const defaults: Theme['default'] = {
+  transition: {
+    duration: '150ms',
+    timingFunction: 'cubic-bezier(0.4, 0, 0.2, 1)',
+  },
+  font: {
+    family: 'var(--font-sans)',
+    featureSettings: 'var(--font-sans--font-feature-settings)',
+    variationSettings: 'var(--font-sans--font-variation-settings)',
+  },
+  monoFont: {
+    family: 'var(--font-mono)',
+    // ...
+  },
+}
+```
+
+## Compatibility Notes
+
+### presetRemToPx
+
+Not needed - use built-in processor instead:
+
+```ts
+presetWind4({
+  preflights: {
+    theme: {
+      process: createRemToPxProcessor(),
+    }
+  },
+})
+```
+
+### presetLegacyCompat
+
+**Not compatible** with preset-wind4 due to `oklch` color model.
+
+## Migration from Wind3
+
+1. Update theme keys according to the table above
+2. Remove `@unocss/reset` imports
+3. Enable `preflights.reset: true`
+4. Test color outputs (oklch vs rgb)
+5. Update any custom theme extensions
+
+```ts
+// Before (wind3)
+theme: {
+  fontFamily: { sans: 'Roboto' },
+  fontSize: { lg: '1.125rem' },
+  breakpoints: { sm: '640px' },
+}
+
+// After (wind4)
+theme: {
+  font: { sans: 'Roboto' },
+  text: { lg: { fontSize: '1.125rem' } },
+  breakpoint: { sm: '640px' },
+}
+```
+
+## When to Use Wind4
+
+Choose **preset-wind4** when:
+- Starting a new project
+- Targeting modern browsers
+- Want built-in reset and CSS variables
+- Following Tailwind v4 conventions
+
+Choose **preset-wind3** when:
+- Need legacy browser support
+- Migrating from Tailwind v3
+- Using presetLegacyCompat
+- Want stable, proven preset
+
+<!-- 
+Source references:
+- https://unocss.dev/presets/wind4
+-->

.agents/skills/unocss/references/transformer-attributify-jsx.md

@@ -0,0 +1,156 @@
+---
+name: transformer-attributify-jsx
+description: Support valueless attributify in JSX/TSX
+---
+
+# Transformer Attributify JSX
+
+Fixes valueless attributify mode in JSX where `<div foo>` becomes `<div foo={true}>`.
+
+## The Problem
+
+In JSX, valueless attributes are transformed:
+
+```jsx
+// You write
+<div m-2 rounded text-teal-400 />
+
+// JSX compiles to
+<div m-2={true} rounded={true} text-teal-400={true} />
+```
+
+The `={true}` breaks UnoCSS attributify detection.
+
+## Installation
+
+```ts
+import { 
+  defineConfig, 
+  presetAttributify, 
+  transformerAttributifyJsx 
+} from 'unocss'
+
+export default defineConfig({
+  presets: [
+    presetAttributify(),
+  ],
+  transformers: [
+    transformerAttributifyJsx(),
+  ],
+})
+```
+
+## How It Works
+
+The transformer converts JSX boolean attributes back to strings:
+
+```jsx
+// Input (after JSX compilation)
+<div m-2={true} rounded={true} />
+
+// Output (transformed)
+<div m-2="" rounded="" />
+```
+
+Now UnoCSS can properly extract the attributify classes.
+
+## Options
+
+```ts
+transformerAttributifyJsx({
+  // Only transform specific attributes
+  // Default: transforms all that match attributify patterns
+  blocklist: ['text', 'font'],
+})
+```
+
+## When to Use
+
+Required when using:
+- React
+- Preact
+- Solid
+- Any JSX-based framework
+
+With valueless attributify syntax:
+
+```jsx
+// This needs the transformer
+<div flex items-center gap-4 />
+
+// This works without transformer (has values)
+<div flex="~" items="center" gap="4" />
+```
+
+## Framework Setup
+
+### React
+
+```ts
+// vite.config.ts
+import React from '@vitejs/plugin-react'
+import UnoCSS from 'unocss/vite'
+
+export default {
+  plugins: [
+    UnoCSS(), // Must be before React
+    React(),
+  ],
+}
+```
+
+```ts
+// uno.config.ts
+import { 
+  defineConfig, 
+  presetAttributify, 
+  presetWind3,
+  transformerAttributifyJsx 
+} from 'unocss'
+
+export default defineConfig({
+  presets: [
+    presetWind3(),
+    presetAttributify(),
+  ],
+  transformers: [
+    transformerAttributifyJsx(),
+  ],
+})
+```
+
+### Preact
+
+Same as React, use `@preact/preset-vite` or `@prefresh/vite`.
+
+### Solid
+
+```ts
+import UnoCSS from 'unocss/vite'
+import solidPlugin from 'vite-plugin-solid'
+
+export default {
+  plugins: [
+    UnoCSS(),
+    solidPlugin(),
+  ],
+}
+```
+
+## TypeScript Support
+
+Add type declarations:
+
+```ts
+// shims.d.ts
+import type { AttributifyAttributes } from '@unocss/preset-attributify'
+
+declare module 'react' {
+  interface HTMLAttributes<T> extends AttributifyAttributes {}
+}
+```
+
+<!-- 
+Source references:
+- https://unocss.dev/transformers/attributify-jsx
+-->

.agents/skills/unocss/references/transformer-compile-class.md

@@ -0,0 +1,128 @@
+---
+name: transformer-compile-class
+description: Compile multiple classes into one hashed class
+---
+
+# Transformer Compile Class
+
+Compiles multiple utility classes into a single hashed class for smaller HTML.
+
+## Installation
+
+```ts
+import { defineConfig, transformerCompileClass } from 'unocss'
+
+export default defineConfig({
+  transformers: [
+    transformerCompileClass(),
+  ],
+})
+```
+
+## Usage
+
+Add `:uno:` prefix to mark classes for compilation:
+
+```html
+<!-- Before -->
+<div class=":uno: text-center sm:text-left">
+  <div class=":uno: text-sm font-bold hover:text-red" />
+</div>
+
+<!-- After -->
+<div class="uno-qlmcrp">
+  <div class="uno-0qw2gr" />
+</div>
+```
+
+## Generated CSS
+
+```css
+.uno-qlmcrp {
+  text-align: center;
+}
+.uno-0qw2gr {
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  font-weight: 700;
+}
+.uno-0qw2gr:hover {
+  --un-text-opacity: 1;
+  color: rgb(248 113 113 / var(--un-text-opacity));
+}
+@media (min-width: 640px) {
+  .uno-qlmcrp {
+    text-align: left;
+  }
+}
+```
+
+## Options
+
+```ts
+transformerCompileClass({
+  // Custom trigger string (default: ':uno:')
+  trigger: ':uno:',
+  
+  // Custom class prefix (default: 'uno-')
+  classPrefix: 'uno-',
+  
+  // Hash function for class names
+  hashFn: (str) => /* custom hash */,
+  
+  // Keep original classes alongside compiled
+  keepOriginal: false,
+})
+```
+
+## Use Cases
+
+- **Smaller HTML** - Reduce repetitive class strings
+- **Obfuscation** - Hide utility class names in production
+- **Performance** - Fewer class attributes to parse
+
+## ESLint Integration
+
+Enforce compile class usage across project:
+
+```json
+{
+  "rules": {
+    "@unocss/enforce-class-compile": "warn"
+  }
+}
+```
+
+This rule:
+- Warns when class attribute doesn't start with `:uno:`
+- Auto-fixes by adding the prefix
+
+Options:
+
+```json
+{
+  "rules": {
+    "@unocss/enforce-class-compile": ["warn", {
+      "prefix": ":uno:",
+      "enableFix": true
+    }]
+  }
+}
+```
+
+## Combining with Other Transformers
+
+```ts
+export default defineConfig({
+  transformers: [
+    transformerVariantGroup(),  // Process variant groups first
+    transformerDirectives(),    // Then directives
+    transformerCompileClass(),  // Compile last
+  ],
+})
+```
+
+<!-- 
+Source references:
+- https://unocss.dev/transformers/compile-class
+-->

.agents/skills/unocss/references/transformer-directives.md

@@ -0,0 +1,157 @@
+---
+name: transformer-directives
+description: CSS directives @apply, @screen, theme(), and icon()
+---
+
+# Transformer Directives
+
+Enables `@apply`, `@screen`, `theme()`, and `icon()` directives in CSS.
+
+## Installation
+
+```ts
+import { defineConfig, transformerDirectives } from 'unocss'
+
+export default defineConfig({
+  transformers: [
+    transformerDirectives(),
+  ],
+})
+```
+
+## @apply
+
+Apply utility classes in CSS:
+
+```css
+.custom-btn {
+  @apply py-2 px-4 font-semibold rounded-lg;
+}
+
+/* With variants - use quotes */
+.custom-btn {
+  @apply 'hover:bg-blue-600 focus:ring-2';
+}
+```
+
+### CSS Custom Property Alternative
+
+For vanilla CSS compatibility:
+
+```css
+.custom-div {
+  --at-apply: text-center my-0 font-medium;
+}
+```
+
+Supported aliases: `--at-apply`, `--uno-apply`, `--uno`
+
+Configure aliases:
+
+```ts
+transformerDirectives({
+  applyVariable: ['--at-apply', '--uno-apply', '--uno'],
+  // or disable: applyVariable: false
+})
+```
+
+## @screen
+
+Create breakpoint media queries:
+
+```css
+.grid {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+}
+
+@screen sm {
+  .grid {
+    grid-template-columns: repeat(3, 1fr);
+  }
+}
+
+@screen lg {
+  .grid {
+    grid-template-columns: repeat(4, 1fr);
+  }
+}
+```
+
+### Breakpoint Variants
+
+```css
+/* Less than breakpoint */
+@screen lt-sm {
+  .item { display: none; }
+}
+
+/* At specific breakpoint only */
+@screen at-md {
+  .item { width: 50%; }
+}
+```
+
+## theme()
+
+Access theme values in CSS:
+
+```css
+.btn-blue {
+  background-color: theme('colors.blue.500');
+  padding: theme('spacing.4');
+  border-radius: theme('borderRadius.lg');
+}
+```
+
+Dot notation paths into your theme config.
+
+## icon()
+
+Convert icon utility to SVG (requires preset-icons):
+
+```css
+.icon-sun {
+  background-image: icon('i-carbon-sun');
+}
+
+/* With custom color */
+.icon-moon {
+  background-image: icon('i-carbon-moon', '#fff');
+}
+
+/* Using theme color */
+.icon-alert {
+  background-image: icon('i-carbon-warning', 'theme("colors.red.500")');
+}
+```
+
+## Complete Example
+
+```css
+.card {
+  @apply rounded-lg shadow-md p-4;
+  background-color: theme('colors.white');
+}
+
+.card-header {
+  @apply 'font-bold text-lg border-b';
+  padding-bottom: theme('spacing.2');
+}
+
+@screen md {
+  .card {
+    @apply flex gap-4;
+  }
+}
+
+.card-icon {
+  background-image: icon('i-carbon-document');
+  @apply w-6 h-6;
+}
+```
+
+<!-- 
+Source references:
+- https://unocss.dev/transformers/directives
+-->

.agents/skills/unocss/references/transformer-variant-group.md

@@ -0,0 +1,97 @@
+---
+name: transformer-variant-group
+description: Shorthand for grouping utilities with common prefixes
+---
+
+# Transformer Variant Group
+
+Enables shorthand syntax for grouping utilities with common prefixes.
+
+## Installation
+
+```ts
+import { defineConfig, transformerVariantGroup } from 'unocss'
+
+export default defineConfig({
+  transformers: [
+    transformerVariantGroup(),
+  ],
+})
+```
+
+## Usage
+
+Group multiple utilities under one variant prefix using parentheses:
+
+```html
+<!-- Before transformation -->
+<div class="hover:(bg-gray-400 font-medium) font-(light mono)" />
+
+<!-- After transformation -->
+<div class="hover:bg-gray-400 hover:font-medium font-light font-mono" />
+```
+
+## Examples
+
+### Hover States
+
+```html
+<button class="hover:(bg-blue-600 text-white scale-105)">
+  Hover me
+</button>
+```
+
+Expands to: `hover:bg-blue-600 hover:text-white hover:scale-105`
+
+### Dark Mode
+
+```html
+<div class="dark:(bg-gray-800 text-white)">
+  Dark content
+</div>
+```
+
+Expands to: `dark:bg-gray-800 dark:text-white`
+
+### Responsive
+
+```html
+<div class="md:(flex items-center gap-4)">
+  Responsive flex
+</div>
+```
+
+Expands to: `md:flex md:items-center md:gap-4`
+
+### Nested Groups
+
+```html
+<div class="lg:hover:(bg-blue-500 text-white)">
+  Large screen hover
+</div>
+```
+
+Expands to: `lg:hover:bg-blue-500 lg:hover:text-white`
+
+### Multiple Prefixes
+
+```html
+<div class="text-(sm gray-600) font-(medium mono)">
+  Styled text
+</div>
+```
+
+Expands to: `text-sm text-gray-600 font-medium font-mono`
+
+## Key Points
+
+- Use parentheses `()` to group utilities
+- The prefix applies to all utilities inside the group
+- Can be combined with any variant (hover, dark, responsive, etc.)
+- Nesting is supported
+- Works in class attributes and other extraction sources
+
+<!-- 
+Source references:
+- https://unocss.dev/transformers/variant-group
+-->

.agents/skills/vite/GENERATION.md

@@ -0,0 +1,5 @@
+# Generation Info
+
+- **Source:** `sources/vite`
+- **Git SHA:** `b40292ce6a7dbbbbac9c6dae5f126b7f44c3e1b7`
+- **Generated:** 2026-01-28

.agents/skills/vite/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: vite
+description: Vite next-generation frontend build tool with fast HMR and optimized builds. Use when configuring Vite, adding plugins, working with dev server, or building for production.
+metadata:
+  author: Anthony Fu
+  version: "2026.1.28"
+  source: Generated from https://github.com/vitejs/vite, scripts located at https://github.com/antfu/skills
+---
+
+Vite is a modern build tool for frontend development featuring instant server start with native ES modules, lightning-fast HMR, and optimized production builds using Rolldown/Rollup. It supports TypeScript, JSX, CSS pre-processors out of the box and has a rich plugin ecosystem.
+
+> The skill is based on Vite 6.x, generated at 2026-01-28.
+
+## Core
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Configuration | Config file setup, defineConfig, conditional and async configs | [core-config](references/core-config.md) |
+| CLI Commands | Dev server, build, preview commands and options | [core-cli](references/core-cli.md) |
+| Core Features | TypeScript, JSX, CSS, HTML processing, JSON handling | [core-features](references/core-features.md) |
+| Using Plugins | Adding, configuring, and ordering plugins | [core-plugins](references/core-plugins.md) |
+
+## Features
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| CSS Handling | CSS modules, pre-processors, PostCSS, Lightning CSS | [features-css](references/features-css.md) |
+| Static Assets | Asset imports, public directory, URL handling | [features-assets](references/features-assets.md) |
+| Glob Import | import.meta.glob, dynamic imports, batch loading | [features-glob-import](references/features-glob-import.md) |
+| Environment Variables | .env files, modes, import.meta.env constants | [features-env](references/features-env.md) |
+| HMR API | Hot Module Replacement client API | [features-hmr](references/features-hmr.md) |
+| Web Workers | Worker imports and configuration | [features-workers](references/features-workers.md) |
+| Dependency Pre-Bundling | optimizeDeps, caching, monorepo setup | [features-dep-bundling](references/features-dep-bundling.md) |
+
+## Build
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Production Build | Build options, browser targets, multi-page apps | [build-production](references/build-production.md) |
+| Library Mode | Building libraries with proper package exports | [build-library](references/build-library.md) |
+| SSR | Server-side rendering setup and configuration | [build-ssr](references/build-ssr.md) |
+
+## Advanced
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| JavaScript API | createServer, build, preview programmatic APIs | [advanced-api](references/advanced-api.md) |
+| Plugin API | Creating Vite plugins, hooks, virtual modules | [advanced-plugin-api](references/advanced-plugin-api.md) |
+| Performance | Optimization tips for dev server and builds | [advanced-performance](references/advanced-performance.md) |
+| Backend Integration | Integrating Vite with traditional backends | [advanced-backend](references/advanced-backend.md) |

.agents/skills/vite/references/advanced-api.md

@@ -0,0 +1,218 @@
+---
+name: advanced-api
+description: Vite's JavaScript API for programmatic usage
+---
+
+# JavaScript API
+
+Vite's APIs are fully typed. Use TypeScript or enable JS type checking for intellisense.
+
+## `createServer`
+
+Create a development server programmatically:
+
+```ts
+import { createServer } from 'vite'
+
+const server = await createServer({
+  configFile: false,
+  root: __dirname,
+  server: {
+    port: 1337
+  }
+})
+
+await server.listen()
+server.printUrls()
+server.bindCLIShortcuts({ print: true })
+```
+
+### ViteDevServer Interface
+
+```ts
+interface ViteDevServer {
+  config: ResolvedConfig
+  middlewares: Connect.Server      // Connect app for custom middleware
+  httpServer: http.Server | null   // Node HTTP server
+  watcher: FSWatcher               // Chokidar watcher
+  ws: WebSocketServer              // WebSocket for HMR
+  moduleGraph: ModuleGraph         // Module import relationships
+  
+  // Transform without HTTP
+  transformRequest(url: string): Promise<TransformResult | null>
+  
+  // Apply HTML transforms
+  transformIndexHtml(url: string, html: string): Promise<string>
+  
+  // Load module for SSR
+  ssrLoadModule(url: string): Promise<Record<string, any>>
+  
+  // Fix SSR error stack traces
+  ssrFixStacktrace(e: Error): void
+  
+  // Control
+  listen(port?: number): Promise<ViteDevServer>
+  restart(): Promise<void>
+  close(): Promise<void>
+}
+```
+
+## `build`
+
+Build for production:
+
+```ts
+import { build } from 'vite'
+
+await build({
+  root: './project',
+  base: '/foo/',
+  build: {
+    rolldownOptions: {
+      // ...
+    }
+  }
+})
+```
+
+## `preview`
+
+Preview production build locally:
+
+```ts
+import { preview } from 'vite'
+
+const previewServer = await preview({
+  preview: {
+    port: 8080,
+    open: true
+  }
+})
+
+previewServer.printUrls()
+```
+
+## `resolveConfig`
+
+Resolve config without starting server:
+
+```ts
+import { resolveConfig } from 'vite'
+
+const config = await resolveConfig(
+  { root: './project' },
+  'serve',        // 'serve' | 'build'
+  'development'   // default mode
+)
+```
+
+## `mergeConfig`
+
+Deep merge two configs:
+
+```ts
+import { mergeConfig } from 'vite'
+
+const merged = mergeConfig(baseConfig, overrideConfig)
+```
+
+Merge callback config:
+
+```ts
+import { defineConfig, mergeConfig } from 'vite'
+
+export default defineConfig((env) =>
+  mergeConfig(configAsCallback(env), configAsObject)
+)
+```
+
+## `loadEnv`
+
+Load .env files:
+
+```ts
+import { loadEnv } from 'vite'
+
+// Load VITE_* vars
+const env = loadEnv('development', process.cwd())
+
+// Load all vars (empty prefix)
+const allEnv = loadEnv('development', process.cwd(), '')
+```
+
+## `searchForWorkspaceRoot`
+
+Find monorepo workspace root:
+
+```ts
+import { searchForWorkspaceRoot } from 'vite'
+
+const workspaceRoot = searchForWorkspaceRoot(process.cwd())
+```
+
+## `normalizePath`
+
+Normalize paths for cross-platform:
+
+```ts
+import { normalizePath } from 'vite'
+
+normalizePath('foo\\bar')  // 'foo/bar'
+```
+
+## `transformWithOxc`
+
+Transform JS/TS with Oxc Transformer:
+
+```ts
+import { transformWithOxc } from 'vite'
+
+const result = await transformWithOxc(
+  code,
+  'file.ts',
+  { target: 'es2020' }
+)
+```
+
+## `preprocessCSS`
+
+Pre-process CSS files:
+
+```ts
+import { preprocessCSS, resolveConfig } from 'vite'
+
+const config = await resolveConfig({}, 'serve')
+const result = await preprocessCSS(code, 'styles.scss', config)
+// result.code - plain CSS
+// result.modules - CSS modules mapping
+```
+
+## `loadConfigFromFile`
+
+Load config file manually:
+
+```ts
+import { loadConfigFromFile } from 'vite'
+
+const result = await loadConfigFromFile(
+  { command: 'serve', mode: 'development' },
+  'vite.config.ts'
+)
+// result.config, result.path, result.dependencies
+```
+
+## InlineConfig
+
+Extends UserConfig with:
+
+```ts
+interface InlineConfig extends UserConfig {
+  configFile?: string | false  // Config file path or false to skip
+  mode?: string
+}
+```
+
+<!-- 
+Source references:
+- https://vite.dev/guide/api-javascript.html
+-->

.agents/skills/vite/references/advanced-backend.md

@@ -0,0 +1,164 @@
+---
+name: advanced-backend
+description: Integrating Vite with traditional backend frameworks
+---
+
+# Backend Integration
+
+Integrate Vite with traditional backends (Rails, Laravel, etc.) for asset serving.
+
+## Configuration
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  server: {
+    cors: {
+      origin: 'http://my-backend.example.com'
+    }
+  },
+  build: {
+    manifest: true,  // Generate .vite/manifest.json
+    rolldownOptions: {
+      input: '/path/to/main.js'  // Override HTML entry
+    }
+  }
+})
+```
+
+Import polyfill in entry:
+
+```ts
+// main.js
+import 'vite/modulepreload-polyfill'
+```
+
+## Development
+
+Inject Vite client and entry in your backend template:
+
+```html
+<!-- Development only -->
+<script type="module" src="http://localhost:5173/@vite/client"></script>
+<script type="module" src="http://localhost:5173/main.js"></script>
+```
+
+### React Setup
+
+Add before other scripts:
+
+```html
+<script type="module">
+  import RefreshRuntime from 'http://localhost:5173/@react-refresh'
+  RefreshRuntime.injectIntoGlobalHook(window)
+  window.$RefreshReg$ = () => {}
+  window.$RefreshSig$ = () => (type) => type
+  window.__vite_plugin_react_preamble_installed__ = true
+</script>
+```
+
+### Asset Proxying
+
+Either:
+1. Proxy static asset requests to Vite
+2. Set `server.origin`:
+
+```ts
+export default defineConfig({
+  server: {
+    origin: 'http://localhost:5173'
+  }
+})
+```
+
+## Production
+
+Build generates `.vite/manifest.json`:
+
+```json
+{
+  "views/foo.js": {
+    "file": "assets/foo-BRBmoGS9.js",
+    "src": "views/foo.js",
+    "isEntry": true,
+    "imports": ["_shared-B7PI925R.js"],
+    "css": ["assets/foo-5UjPuW-k.css"]
+  },
+  "_shared-B7PI925R.js": {
+    "file": "assets/shared-B7PI925R.js",
+    "css": ["assets/shared-ChJ_j-JJ.css"]
+  }
+}
+```
+
+## Rendering Tags
+
+For entry `views/foo.js`, render in this order:
+
+```html
+<!-- 1. Entry CSS -->
+<link rel="stylesheet" href="/assets/foo-5UjPuW-k.css" />
+
+<!-- 2. Imported chunks' CSS (recursive) -->
+<link rel="stylesheet" href="/assets/shared-ChJ_j-JJ.css" />
+
+<!-- 3. Entry script -->
+<script type="module" src="/assets/foo-BRBmoGS9.js"></script>
+
+<!-- 4. Optional: preload imports -->
+<link rel="modulepreload" href="/assets/shared-B7PI925R.js" />
+```
+
+## Manifest Structure
+
+```ts
+interface ManifestChunk {
+  src?: string           // Input file name
+  file: string          // Output file name
+  css?: string[]        // CSS files (JS chunks only)
+  assets?: string[]     // Non-CSS assets (JS chunks only)
+  isEntry?: boolean     // Is entry point
+  isDynamicEntry?: boolean  // Is dynamic import
+  imports?: string[]    // Static imports (manifest keys)
+  dynamicImports?: string[]  // Dynamic imports (manifest keys)
+}
+```
+
+## Processing Imports
+
+Recursively collect all imported chunks:
+
+```ts
+function getImportedChunks(manifest, name) {
+  const seen = new Set()
+  const chunks = []
+  
+  function collect(chunk) {
+    for (const file of chunk.imports ?? []) {
+      if (seen.has(file)) continue
+      seen.add(file)
+      
+      const importee = manifest[file]
+      collect(importee)
+      chunks.push(importee)
+    }
+  }
+  
+  collect(manifest[name])
+  return chunks
+}
+```
+
+## Existing Integrations
+
+Check [Awesome Vite](https://github.com/vitejs/awesome-vite#integrations-with-backends) for:
+- Laravel (laravel-vite)
+- Rails
+- Django
+- Flask
+- And more
+
+<!-- 
+Source references:
+- https://vite.dev/guide/backend-integration.html
+-->

.agents/skills/vite/references/advanced-performance.md

@@ -0,0 +1,168 @@
+---
+name: advanced-performance
+description: Performance optimization tips for Vite dev server and builds
+---
+
+# Performance Optimization
+
+## Browser Setup
+
+- Use dev-only browser profile without extensions
+- Disable "Disable Cache" in DevTools when using Vite
+- Extensions can interfere with requests and slow startup
+
+## Audit Plugin Performance
+
+1. **Lazy load large dependencies** in plugins
+2. **Avoid long operations** in `buildStart`, `config`, `configResolved`
+3. **Optimize transform hooks** - check `id` extension before processing
+
+Debug transform times:
+
+```bash
+vite --debug plugin-transform
+```
+
+Use [vite-plugin-inspect](https://github.com/antfu/vite-plugin-inspect) to inspect transforms.
+
+## Profiling
+
+```bash
+vite --profile
+# Visit site, press 'p + enter' to record .cpuprofile
+# Open in https://www.speedscope.app
+```
+
+## Reduce Resolve Operations
+
+Be explicit with extensions to avoid filesystem checks:
+
+```ts
+// Slow: checks .mjs, .js, .mts, .ts, .jsx, .tsx, .json
+import Component from './Component'
+
+// Fast: direct hit
+import Component from './Component.tsx'
+```
+
+Enable TypeScript path resolution for explicit imports:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true
+  }
+}
+```
+
+## Avoid Barrel Files
+
+Barrel files (`index.js` re-exporting everything) cause all files to load:
+
+```ts
+// Slow: loads all utils
+import { slash } from './utils'
+
+// Fast: loads only slash.js
+import { slash } from './utils/slash.js'
+```
+
+## Warm Up Frequently Used Files
+
+Pre-transform files that are always loaded:
+
+```ts
+export default defineConfig({
+  server: {
+    warmup: {
+      clientFiles: [
+        './src/components/BigComponent.vue',
+        './src/utils/big-utils.js'
+      ],
+      ssrFiles: ['./src/server/modules/*.js']
+    }
+  }
+})
+```
+
+Find files to warm up:
+
+```bash
+vite --debug transform
+```
+
+## Use Native/Less Tooling
+
+**Do less work:**
+- CSS instead of Sass/Less (PostCSS has nesting)
+- Don't transform SVGs to components - import as strings/URLs
+- Skip Babel in `@vitejs/plugin-react` if not needed
+
+**Use native tools:**
+- Try Lightning CSS for faster CSS processing
+
+```ts
+export default defineConfig({
+  css: {
+    transformer: 'lightningcss'
+  }
+})
+```
+
+## Server Options
+
+### Open Browser Automatically
+
+Triggers warmup of entry point:
+
+```ts
+export default defineConfig({
+  server: {
+    open: true
+  }
+})
+```
+
+### Limit File Watching
+
+```ts
+export default defineConfig({
+  server: {
+    watch: {
+      ignored: ['**/large-folder/**']
+    }
+  }
+})
+```
+
+## Build Performance
+
+### Disable Reporting
+
+Skip gzip size calculation for large projects:
+
+```ts
+export default defineConfig({
+  build: {
+    reportCompressedSize: false
+  }
+})
+```
+
+### Sourcemaps
+
+Disable if not needed:
+
+```ts
+export default defineConfig({
+  build: {
+    sourcemap: false
+  }
+})
+```
+
+<!-- 
+Source references:
+- https://vite.dev/guide/performance.html
+-->

.agents/skills/vite/references/advanced-plugin-api.md

@@ -0,0 +1,258 @@
+---
+name: advanced-plugin-api
+description: Creating Vite plugins, hooks, virtual modules, and client-server communication
+---
+
+# Plugin API
+
+Vite plugins extend Rolldown's plugin interface with Vite-specific hooks.
+
+## Basic Plugin Structure
+
+```ts
+export default function myPlugin(options = {}) {
+  return {
+    name: 'vite-plugin-my-plugin',
+    
+    // Hooks...
+  }
+}
+```
+
+## Naming Conventions
+
+- Vite-only plugins: `vite-plugin-*`
+- Rollup-compatible: `rollup-plugin-*`
+- Framework-specific: `vite-plugin-vue-*`, `vite-plugin-react-*`
+
+## Universal Hooks (from Rolldown)
+
+Called on server start:
+- `options` - Modify Rolldown options
+- `buildStart` - Build starting
+
+Called per module request:
+- `resolveId` - Resolve import paths
+- `load` - Load module content
+- `transform` - Transform module code
+
+Called on server close:
+- `buildEnd`
+- `closeBundle`
+
+## Vite-Specific Hooks
+
+### `config`
+
+Modify config before resolution:
+
+```ts
+{
+  name: 'modify-config',
+  config(config, { command, mode }) {
+    if (command === 'build') {
+      return {
+        resolve: {
+          alias: { foo: 'bar' }
+        }
+      }
+    }
+  }
+}
+```
+
+### `configResolved`
+
+Access final resolved config:
+
+```ts
+{
+  name: 'read-config',
+  configResolved(config) {
+    this.config = config
+  }
+}
+```
+
+### `configureServer`
+
+Add dev server middleware:
+
+```ts
+{
+  name: 'configure-server',
+  configureServer(server) {
+    // Before Vite's middlewares
+    server.middlewares.use((req, res, next) => {
+      // Handle request
+      next()
+    })
+    
+    // Return function to run after Vite's middlewares
+    return () => {
+      server.middlewares.use((req, res, next) => {
+        // Post middleware
+      })
+    }
+  }
+}
+```
+
+### `transformIndexHtml`
+
+Transform HTML files:
+
+```ts
+{
+  name: 'html-transform',
+  transformIndexHtml(html) {
+    return html.replace(/<title>(.*?)<\/title>/, '<title>New Title</title>')
+  }
+}
+```
+
+Inject tags:
+
+```ts
+{
+  name: 'html-inject',
+  transformIndexHtml() {
+    return {
+      tags: [
+        {
+          tag: 'script',
+          attrs: { src: '/inject.js' },
+          injectTo: 'body'  // 'head' | 'body' | 'head-prepend' | 'body-prepend'
+        }
+      ]
+    }
+  }
+}
+```
+
+### `handleHotUpdate`
+
+Custom HMR handling:
+
+```ts
+{
+  name: 'custom-hmr',
+  handleHotUpdate({ file, server, modules }) {
+    if (file.endsWith('.custom')) {
+      server.ws.send({
+        type: 'custom',
+        event: 'custom-update',
+        data: { file }
+      })
+      return []  // Prevent default HMR
+    }
+  }
+}
+```
+
+## Virtual Modules
+
+Provide build-time information to source code:
+
+```ts
+export default function myPlugin() {
+  const virtualModuleId = 'virtual:my-module'
+  const resolvedId = '\0' + virtualModuleId
+
+  return {
+    name: 'virtual-module',
+    
+    resolveId(id) {
+      if (id === virtualModuleId) {
+        return resolvedId
+      }
+    },
+    
+    load(id) {
+      if (id === resolvedId) {
+        return `export const msg = "from virtual module"`
+      }
+    }
+  }
+}
+```
+
+Usage:
+
+```ts
+import { msg } from 'virtual:my-module'
+```
+
+## Client-Server Communication
+
+### Server to Client
+
+```ts
+{
+  configureServer(server) {
+    server.ws.on('connection', () => {
+      server.ws.send('my:greetings', { msg: 'hello' })
+    })
+  }
+}
+```
+
+Client receives:
+
+```ts
+if (import.meta.hot) {
+  import.meta.hot.on('my:greetings', (data) => {
+    console.log(data.msg)
+  })
+}
+```
+
+### Client to Server
+
+```ts
+// Client
+if (import.meta.hot) {
+  import.meta.hot.send('my:from-client', { msg: 'Hey!' })
+}
+
+// Server (in plugin)
+{
+  configureServer(server) {
+    server.ws.on('my:from-client', (data, client) => {
+      console.log(data.msg)
+      client.send('my:reply', { msg: 'Got it!' })
+    })
+  }
+}
+```
+
+## Transform with Filtering
+
+```ts
+{
+  name: 'transform-js',
+  transform: {
+    filter: {
+      id: /\.js$/  // Only .js files
+    },
+    handler(code, id) {
+      return transformCode(code)
+    }
+  }
+}
+```
+
+## Path Normalization
+
+Use POSIX separators for cross-platform compatibility:
+
+```ts
+import { normalizePath } from 'vite'
+
+normalizePath('foo\\bar')  // 'foo/bar'
+```
+
+<!-- 
+Source references:
+- https://vite.dev/guide/api-plugin.html
+-->

.agents/skills/vite/references/build-library.md

@@ -0,0 +1,172 @@
+---
+name: build-library
+description: Building libraries with Vite including proper package.json exports
+---
+
+# Library Mode
+
+Build browser-oriented libraries for distribution.
+
+## Basic Configuration
+
+```ts
+import { resolve } from 'path'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  build: {
+    lib: {
+      entry: resolve(__dirname, 'lib/main.js'),
+      name: 'MyLib',           // Global variable name for UMD
+      fileName: 'my-lib'       // Output filename (without extension)
+    },
+    rolldownOptions: {
+      external: ['vue'],       // Don't bundle these
+      output: {
+        globals: {
+          vue: 'Vue'           // Global var for externals in UMD
+        }
+      }
+    }
+  }
+})
+```
+
+## Multiple Entry Points
+
+```ts
+export default defineConfig({
+  build: {
+    lib: {
+      entry: {
+        'my-lib': resolve(__dirname, 'lib/main.js'),
+        'secondary': resolve(__dirname, 'lib/secondary.js')
+      },
+      name: 'MyLib'
+    }
+  }
+})
+```
+
+## Output Formats
+
+Single entry defaults: `['es', 'umd']`
+Multiple entries defaults: `['es', 'cjs']`
+
+```ts
+export default defineConfig({
+  build: {
+    lib: {
+      entry: resolve(__dirname, 'lib/main.js'),
+      formats: ['es', 'cjs', 'umd', 'iife']
+    }
+  }
+})
+```
+
+## Custom File Names
+
+```ts
+export default defineConfig({
+  build: {
+    lib: {
+      entry: resolve(__dirname, 'lib/main.js'),
+      fileName: (format, entryName) => `${entryName}.${format}.js`,
+      cssFileName: 'styles'  // For bundled CSS
+    }
+  }
+})
+```
+
+## Package.json Configuration
+
+### Single Entry
+
+```json
+{
+  "name": "my-lib",
+  "type": "module",
+  "files": ["dist"],
+  "main": "./dist/my-lib.umd.cjs",
+  "module": "./dist/my-lib.js",
+  "exports": {
+    ".": {
+      "import": "./dist/my-lib.js",
+      "require": "./dist/my-lib.umd.cjs"
+    }
+  }
+}
+```
+
+### Multiple Entries
+
+```json
+{
+  "name": "my-lib",
+  "type": "module",
+  "files": ["dist"],
+  "main": "./dist/my-lib.cjs",
+  "module": "./dist/my-lib.js",
+  "exports": {
+    ".": {
+      "import": "./dist/my-lib.js",
+      "require": "./dist/my-lib.cjs"
+    },
+    "./secondary": {
+      "import": "./dist/secondary.js",
+      "require": "./dist/secondary.cjs"
+    }
+  }
+}
+```
+
+### With CSS
+
+```json
+{
+  "exports": {
+    ".": {
+      "import": "./dist/my-lib.js",
+      "require": "./dist/my-lib.umd.cjs"
+    },
+    "./style.css": "./dist/my-lib.css"
+  }
+}
+```
+
+## Library Entry File
+
+```ts
+// lib/main.js
+import Foo from './Foo.vue'
+import Bar from './Bar.vue'
+
+export { Foo, Bar }
+```
+
+## Environment Variables
+
+In library mode:
+- `import.meta.env.*` is statically replaced
+- `process.env.*` is NOT replaced (consumers can change it)
+
+To replace `process.env`:
+
+```ts
+export default defineConfig({
+  define: {
+    'process.env.NODE_ENV': '"production"'
+  }
+})
+```
+
+## Notes
+
+- `assetsInlineLimit` is ignored - assets always inlined
+- `cssCodeSplit` defaults to `false`
+- For non-browser libraries, consider using [tsdown](https://tsdown.dev/) or Rolldown directly
+
+<!-- 
+Source references:
+- https://vite.dev/guide/build.html#library-mode
+-->

.agents/skills/vite/references/build-production.md

@@ -0,0 +1,220 @@
+---
+name: build-production
+description: Building for production including targets, multi-page apps, and optimizations
+---
+
+# Building for Production
+
+## Basic Build
+
+```bash
+vite build
+```
+
+Uses `<root>/index.html` as entry point, outputs to `dist/`.
+
+## Browser Compatibility
+
+Default target: Baseline Widely Available browsers (Chrome 111+, Edge 111+, Firefox 114+, Safari 16.4+).
+
+```ts
+export default defineConfig({
+  build: {
+    target: 'es2020',  // Or specific browsers
+    // target: ['chrome64', 'firefox78', 'safari12']
+  }
+})
+```
+
+For legacy browsers:
+
+```bash
+npm add -D @vitejs/plugin-legacy
+```
+
+```ts
+import legacy from '@vitejs/plugin-legacy'
+
+export default defineConfig({
+  plugins: [
+    legacy({
+      targets: ['defaults', 'not IE 11']
+    })
+  ]
+})
+```
+
+## Output Configuration
+
+```ts
+export default defineConfig({
+  build: {
+    outDir: 'dist',           // Output directory
+    assetsDir: 'assets',      // Assets subdirectory
+    emptyOutDir: true,        // Clear outDir before build
+    sourcemap: true,          // Generate sourcemaps
+    // sourcemap: 'inline' | 'hidden'
+  }
+})
+```
+
+## Public Base Path
+
+For deploying under a subpath:
+
+```ts
+export default defineConfig({
+  base: '/my-app/'
+})
+```
+
+Relative base (works anywhere):
+
+```ts
+export default defineConfig({
+  base: './'
+})
+```
+
+Access in code:
+
+```ts
+const base = import.meta.env.BASE_URL
+```
+
+## Multi-Page App
+
+```ts
+import { resolve } from 'path'
+
+export default defineConfig({
+  build: {
+    rolldownOptions: {
+      input: {
+        main: resolve(__dirname, 'index.html'),
+        nested: resolve(__dirname, 'nested/index.html')
+      }
+    }
+  }
+})
+```
+
+## Minification
+
+```ts
+export default defineConfig({
+  build: {
+    minify: 'oxc',     // Default, fastest
+    // minify: 'terser',  // More options, slower
+    // minify: false,     // Disable
+    
+    terserOptions: {   // If using terser
+      compress: {
+        drop_console: true
+      }
+    }
+  }
+})
+```
+
+## Chunk Strategy
+
+```ts
+export default defineConfig({
+  build: {
+    rolldownOptions: {
+      output: {
+        codeSplitting: {
+          // Manual chunks configuration
+        }
+      }
+    },
+    chunkSizeWarningLimit: 500  // KB
+  }
+})
+```
+
+## CSS Options
+
+```ts
+export default defineConfig({
+  build: {
+    cssCodeSplit: true,         // CSS per async chunk
+    cssMinify: 'lightningcss',  // or 'esbuild'
+    cssTarget: 'chrome61'       // Different from JS target
+  }
+})
+```
+
+## Asset Handling
+
+```ts
+export default defineConfig({
+  build: {
+    assetsInlineLimit: 4096,    // Inline assets < 4KB as base64
+    copyPublicDir: true         // Copy public/ to outDir
+  }
+})
+```
+
+## Manifest
+
+Generate manifest for backend integration:
+
+```ts
+export default defineConfig({
+  build: {
+    manifest: true  // .vite/manifest.json
+  }
+})
+```
+
+## Watch Mode
+
+Rebuild on file changes:
+
+```bash
+vite build --watch
+```
+
+```ts
+export default defineConfig({
+  build: {
+    watch: {}  // Enable programmatically
+  }
+})
+```
+
+## Load Error Handling
+
+Handle dynamic import failures (e.g., after deployment):
+
+```ts
+window.addEventListener('vite:preloadError', (event) => {
+  window.location.reload()
+})
+```
+
+## Build Optimizations (Automatic)
+
+- **CSS code splitting** - CSS per async chunk
+- **Preload directives** - `<link rel="modulepreload">`
+- **Async chunk optimization** - Parallel fetching of dependencies
+
+## License Generation
+
+Generate license file for dependencies:
+
+```ts
+export default defineConfig({
+  build: {
+    license: true  // .vite/license.md
+  }
+})
+```
+
+<!-- 
+Source references:
+- https://vite.dev/guide/build.html
+- https://vite.dev/config/build-options.html
+-->

.agents/skills/vite/references/build-ssr.md

@@ -0,0 +1,194 @@
+---
+name: build-ssr
+description: Server-side rendering setup and configuration with Vite
+---
+
+# Server-Side Rendering (SSR)
+
+Low-level API for framework authors. For applications, use higher-level tools from [Awesome Vite SSR](https://github.com/vitejs/awesome-vite#ssr).
+
+## Project Structure
+
+```
+├── index.html
+├── server.js              # Express/Node server
+└── src/
+    ├── main.js            # Universal app code
+    ├── entry-client.js    # Mounts app to DOM
+    └── entry-server.js    # Renders app with SSR API
+```
+
+## index.html
+
+```html
+<!DOCTYPE html>
+<html>
+  <body>
+    <div id="app"><!--ssr-outlet--></div>
+    <script type="module" src="/src/entry-client.js"></script>
+  </body>
+</html>
+```
+
+## Development Server
+
+```ts
+// server.js
+import express from 'express'
+import { createServer as createViteServer } from 'vite'
+
+async function createServer() {
+  const app = express()
+
+  const vite = await createViteServer({
+    server: { middlewareMode: true },
+    appType: 'custom'
+  })
+
+  app.use(vite.middlewares)
+
+  app.use('*all', async (req, res, next) => {
+    const url = req.originalUrl
+
+    try {
+      // 1. Read index.html
+      let template = fs.readFileSync(
+        path.resolve(__dirname, 'index.html'),
+        'utf-8'
+      )
+
+      // 2. Apply Vite transforms
+      template = await vite.transformIndexHtml(url, template)
+
+      // 3. Load server entry
+      const { render } = await vite.ssrLoadModule('/src/entry-server.js')
+
+      // 4. Render app HTML
+      const appHtml = await render(url)
+
+      // 5. Inject into template
+      const html = template.replace('<!--ssr-outlet-->', appHtml)
+
+      res.status(200).set({ 'Content-Type': 'text/html' }).end(html)
+    } catch (e) {
+      vite.ssrFixStacktrace(e)
+      next(e)
+    }
+  })
+
+  app.listen(5173)
+}
+
+createServer()
+```
+
+## Conditional Logic
+
+```ts
+if (import.meta.env.SSR) {
+  // Server-only code (tree-shaken on client)
+}
+```
+
+## Production Build
+
+```json
+{
+  "scripts": {
+    "build:client": "vite build --outDir dist/client",
+    "build:server": "vite build --outDir dist/server --ssr src/entry-server.js"
+  }
+}
+```
+
+### Production Server
+
+```ts
+// Differences from dev:
+// 1. Use dist/client/index.html as template
+// 2. Use import('./dist/server/entry-server.js') instead of ssrLoadModule
+// 3. Serve static files from dist/client
+```
+
+## SSR Manifest
+
+For preload directives:
+
+```bash
+vite build --outDir dist/client --ssrManifest
+```
+
+Generates `dist/client/.vite/ssr-manifest.json` with module-to-chunk mappings.
+
+## SSR Externals
+
+Dependencies are externalized by default. To transform with Vite:
+
+```ts
+export default defineConfig({
+  ssr: {
+    noExternal: ['package-that-needs-transform'],
+    external: ['package-to-externalize']
+  }
+})
+```
+
+## SSR-specific Plugin Logic
+
+```ts
+export function mySSRPlugin() {
+  return {
+    name: 'my-ssr',
+    transform(code, id, options) {
+      if (options?.ssr) {
+        // SSR-specific transform
+      }
+    }
+  }
+}
+```
+
+## SSR Target
+
+```ts
+export default defineConfig({
+  ssr: {
+    target: 'node',      // Default
+    // target: 'webworker'  // For edge runtimes
+  }
+})
+```
+
+## SSR Bundle
+
+Bundle all dependencies (for workers):
+
+```ts
+export default defineConfig({
+  ssr: {
+    noExternal: true  // Bundle everything
+  }
+})
+```
+
+## Resolve Conditions
+
+```ts
+export default defineConfig({
+  ssr: {
+    resolve: {
+      conditions: ['node'],
+      externalConditions: ['node']
+    }
+  }
+})
+```
+
+## Pre-Rendering / SSG
+
+Pre-render routes with known data into static HTML at build time.
+
+<!-- 
+Source references:
+- https://vite.dev/guide/ssr.html
+-->

.agents/skills/vite/references/core-cli.md

@@ -0,0 +1,137 @@
+---
+name: core-cli
+description: Vite CLI commands for development, building, and previewing
+---
+
+# Vite CLI
+
+## Dev Server
+
+Start the development server:
+
+```bash
+vite [root]
+vite dev [root]   # alias
+vite serve [root] # alias
+```
+
+### Dev Server Options
+
+| Option | Description |
+|--------|-------------|
+| `--host [host]` | Specify hostname (use `0.0.0.0` for LAN access) |
+| `--port <port>` | Specify port (default: 5173) |
+| `--open [path]` | Open browser on startup |
+| `--cors` | Enable CORS |
+| `--strictPort` | Exit if port is in use |
+| `--force` | Force optimizer to re-bundle dependencies |
+| `-c, --config <file>` | Use specified config file |
+| `--base <path>` | Public base path |
+| `-m, --mode <mode>` | Set env mode |
+| `-l, --logLevel <level>` | info \| warn \| error \| silent |
+| `--clearScreen` | Allow/disable clear screen when logging |
+
+## Build
+
+Build for production:
+
+```bash
+vite build [root]
+```
+
+### Build Options
+
+| Option | Description |
+|--------|-------------|
+| `--target <target>` | Transpile target (default: `"modules"`) |
+| `--outDir <dir>` | Output directory (default: `dist`) |
+| `--assetsDir <dir>` | Assets directory under outDir (default: `"assets"`) |
+| `--assetsInlineLimit <number>` | Inline threshold in bytes (default: 4096) |
+| `--ssr [entry]` | Build for SSR |
+| `--sourcemap [output]` | Generate source maps (`boolean \| "inline" \| "hidden"`) |
+| `--minify [minifier]` | Minifier (`boolean \| "oxc" \| "terser" \| "esbuild"`) |
+| `--manifest [name]` | Generate build manifest JSON |
+| `--ssrManifest [name]` | Generate SSR manifest JSON |
+| `--emptyOutDir` | Force empty outDir |
+| `-w, --watch` | Watch mode for rebuilding |
+
+## Preview
+
+Locally preview the production build:
+
+```bash
+vite preview [root]
+```
+
+### Preview Options
+
+| Option | Description |
+|--------|-------------|
+| `--host [host]` | Specify hostname |
+| `--port <port>` | Specify port |
+| `--strictPort` | Exit if port is in use |
+| `--open [path]` | Open browser on startup |
+| `--outDir <dir>` | Output directory (default: `dist`) |
+
+## Package Scripts
+
+Typical `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  }
+}
+```
+
+## Running Vite
+
+```bash
+# With npm
+npx vite
+
+# With pnpm
+pnpm vite
+
+# With yarn
+yarn vite
+
+# With bun
+bunx vite
+```
+
+## Scaffolding New Project
+
+```bash
+# Interactive prompts
+npm create vite@latest
+
+# With project name and template
+npm create vite@latest my-app -- --template vue-ts
+
+# Available templates: vanilla, vanilla-ts, vue, vue-ts, react, react-ts,
+# react-swc, react-swc-ts, preact, preact-ts, lit, lit-ts, svelte, svelte-ts,
+# solid, solid-ts, qwik, qwik-ts
+```
+
+## Debugging
+
+```bash
+# Debug plugin transforms
+vite --debug plugin-transform
+
+# Debug with profiling
+vite --profile
+# Then press 'p + enter' to record .cpuprofile
+
+# Filter debug logs
+vite --debug -f plugin-transform
+```
+
+<!-- 
+Source references:
+- https://vite.dev/guide/cli.html
+-->

.agents/skills/vite/references/core-config.md

@@ -0,0 +1,176 @@
+---
+name: core-config
+description: Vite configuration file setup, defineConfig helper, conditional and async configs
+---
+
+# Vite Configuration
+
+Vite automatically resolves a config file named `vite.config.*` in the project root.
+
+## Basic Configuration
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  // config options
+})
+```
+
+Use `defineConfig` for TypeScript intellisense. Alternatively, use JSDoc annotations:
+
+```js
+/** @type {import('vite').UserConfig} */
+export default {
+  // config options
+}
+```
+
+## Conditional Config
+
+Export a function to conditionally determine options based on command, mode, or build type:
+
+```ts
+import { defineConfig } from 'vite'
+
+export default defineConfig(({ command, mode, isSsrBuild, isPreview }) => {
+  if (command === 'serve') {
+    // dev specific config
+    return {
+      define: {
+        __DEV__: true
+      }
+    }
+  } else {
+    // build specific config
+    return {
+      define: {
+        __DEV__: false
+      }
+    }
+  }
+})
+```
+
+- `command` is `'serve'` during dev (`vite`, `vite dev`, `vite serve`) and `'build'` for production
+- `mode` defaults to `'development'` for serve, `'production'` for build
+
+## Async Config
+
+```ts
+import { defineConfig } from 'vite'
+
+export default defineConfig(async ({ command, mode }) => {
+  const data = await fetchRemoteConfig()
+  return {
+    // config using fetched data
+  }
+})
+```
+
+## Key Configuration Options
+
+### Root and Base
+
+```ts
+export default defineConfig({
+  root: './src',           // Project root directory (where index.html is)
+  base: '/my-app/',        // Public base path for assets
+  publicDir: 'public',     // Static assets directory
+  cacheDir: 'node_modules/.vite'  // Cache directory
+})
+```
+
+### Resolve Aliases
+
+```ts
+import { resolve } from 'path'
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@': resolve(__dirname, 'src'),
+      '~': resolve(__dirname, 'src/components')
+    },
+    // File extensions to try for imports without extension
+    extensions: ['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json']
+  }
+})
+```
+
+### Define Global Constants
+
+```ts
+export default defineConfig({
+  define: {
+    __APP_VERSION__: JSON.stringify('1.0.0'),
+    __API_URL__: JSON.stringify('https://api.example.com')
+  }
+})
+```
+
+Values must be JSON-serializable or a single identifier. Add TypeScript declarations:
+
+```ts
+// vite-env.d.ts
+declare const __APP_VERSION__: string
+declare const __API_URL__: string
+```
+
+### JSON Handling
+
+```ts
+export default defineConfig({
+  json: {
+    namedExports: true,  // Support named imports from JSON
+    stringify: 'auto'    // Stringify large JSON for performance
+  }
+})
+```
+
+## Using Environment Variables in Config
+
+Variables from `.env` files are NOT automatically available in config. Use `loadEnv`:
+
+```ts
+import { defineConfig, loadEnv } from 'vite'
+
+export default defineConfig(({ mode }) => {
+  // Load env vars from .env files
+  const env = loadEnv(mode, process.cwd(), '')
+  
+  return {
+    define: {
+      __APP_ENV__: JSON.stringify(env.APP_ENV)
+    },
+    server: {
+      port: env.APP_PORT ? Number(env.APP_PORT) : 5173
+    }
+  }
+})
+```
+
+## Specifying Config File
+
+```bash
+vite --config my-config.ts
+```
+
+## Config Loading Methods
+
+```bash
+# Default: bundle with Rolldown (may have issues in monorepos)
+vite
+
+# Use module runner (no temp file, transforms on the fly)
+vite --configLoader runner
+
+# Use native runtime (requires Node.js with TypeScript support)
+vite --configLoader native
+```
+
+<!-- 
+Source references:
+- https://vite.dev/config/
+-->

.agents/skills/vite/references/core-features.md

@@ -0,0 +1,170 @@
+---
+name: core-features
+description: Core Vite features including TypeScript, JSX, CSS, and HTML processing
+---
+
+# Core Features
+
+## TypeScript
+
+Vite supports `.ts` files out of the box with transpilation via Oxc Transformer (20-30x faster than tsc).
+
+### Important: Transpile Only
+
+Vite does NOT perform type checking. Run type checking separately:
+
+```bash
+# Production build
+tsc --noEmit && vite build
+
+# During development (separate process)
+tsc --noEmit --watch
+
+# Or use vite-plugin-checker for browser error reporting
+```
+
+### TypeScript Configuration
+
+Required `tsconfig.json` settings:
+
+```json
+{
+  "compilerOptions": {
+    "isolatedModules": true,
+    "useDefineForClassFields": true,
+    "skipLibCheck": true
+  }
+}
+```
+
+### Client Types
+
+Add Vite's client types for `import.meta.env` and asset imports:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["vite/client"]
+  }
+}
+```
+
+This provides types for:
+- Asset imports (`.svg`, `.png`, etc.)
+- `import.meta.env` constants
+- `import.meta.hot` HMR API
+
+### Custom Type Overrides
+
+Override default asset import types:
+
+```ts
+// vite-env-override.d.ts
+declare module '*.svg' {
+  const content: React.FC<React.SVGProps<SVGElement>>
+  export default content
+}
+```
+
+### Path Aliases with tsconfig
+
+Enable tsconfig paths resolution:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  resolve: {
+    tsconfigPaths: true
+  }
+})
+```
+
+## JSX
+
+`.jsx` and `.tsx` files are supported out of the box. Custom JSX configuration:
+
+```ts
+export default defineConfig({
+  oxc: {
+    jsx: {
+      runtime: 'classic',  // or 'automatic'
+      pragma: 'h',
+      pragmaFrag: 'Fragment'
+    },
+    // Auto-inject JSX helpers
+    jsxInject: `import React from 'react'`
+  }
+})
+```
+
+## HTML
+
+`index.html` is the entry point, not tucked away in `public/`. Vite processes it as part of the module graph.
+
+### Supported Elements
+
+Vite processes these HTML element attributes:
+
+- `<script type="module" src>`
+- `<link href>` (stylesheets)
+- `<img src>`, `<img srcset>`
+- `<video src>`, `<video poster>`
+- `<audio src>`
+- `<source src>`, `<source srcset>`
+- `<meta content>` (for og:image, twitter:image, etc.)
+
+### Opt-out of Processing
+
+```html
+<script vite-ignore type="module" src="https://cdn.example.com/lib.js"></script>
+```
+
+### Multi-Page Apps
+
+Access any HTML file by its path:
+
+- `<root>/index.html` → `http://localhost:5173/`
+- `<root>/about.html` → `http://localhost:5173/about.html`
+- `<root>/blog/index.html` → `http://localhost:5173/blog/index.html`
+
+## JSON
+
+Direct import with named exports support:
+
+```ts
+// Import entire object
+import json from './data.json'
+
+// Named imports (tree-shakeable)
+import { field } from './data.json'
+```
+
+## Framework Support
+
+Official framework plugins:
+
+| Framework | Plugin |
+|-----------|--------|
+| Vue 3 | `@vitejs/plugin-vue` |
+| Vue 3 JSX | `@vitejs/plugin-vue-jsx` |
+| React | `@vitejs/plugin-react` |
+| React (SWC) | `@vitejs/plugin-react-swc` |
+| React Server Components | `@vitejs/plugin-rsc` |
+| Legacy browsers | `@vitejs/plugin-legacy` |
+
+## Content Security Policy
+
+Configure nonce for CSP:
+
+```ts
+export default defineConfig({
+  html: {
+    cspNonce: 'PLACEHOLDER'  // Replace per-request
+  }
+})
+```
+
+<!-- 
+Source references:
+- https://vite.dev/guide/features.html
+-->

.agents/skills/vite/references/core-plugins.md

@@ -0,0 +1,154 @@
+---
+name: core-plugins
+description: Adding, configuring, and ordering Vite plugins
+---
+
+# Using Plugins
+
+Vite extends Rolldown's plugin interface with extra Vite-specific options.
+
+## Adding Plugins
+
+Install and add to config:
+
+```bash
+npm add -D @vitejs/plugin-vue
+```
+
+```ts
+// vite.config.ts
+import vue from '@vitejs/plugin-vue'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [vue()]
+})
+```
+
+## Plugin Arrays
+
+Plugins can return arrays (for complex features):
+
+```ts
+// Framework plugin returning multiple plugins
+export default function framework(config) {
+  return [
+    frameworkRefresh(config),
+    frameworkDevtools(config)
+  ]
+}
+```
+
+## Conditional Plugins
+
+Falsy values are ignored:
+
+```ts
+export default defineConfig({
+  plugins: [
+    vue(),
+    process.env.ANALYZE && visualizer()  // Only if ANALYZE is set
+  ]
+})
+```
+
+## Enforcing Plugin Order
+
+Control when plugin runs relative to Vite core:
+
+```ts
+export default defineConfig({
+  plugins: [
+    {
+      ...somePlugin(),
+      enforce: 'pre'  // Before Vite core plugins
+    },
+    {
+      ...anotherPlugin(),
+      enforce: 'post'  // After Vite build plugins
+    }
+  ]
+})
+```
+
+**Order:**
+1. Alias
+2. Plugins with `enforce: 'pre'`
+3. Vite core plugins
+4. Plugins without enforce
+5. Vite build plugins
+6. Plugins with `enforce: 'post'`
+7. Vite post-build plugins (minify, manifest)
+
+## Conditional Application
+
+Apply only during serve or build:
+
+```ts
+export default defineConfig({
+  plugins: [
+    {
+      ...typescript2(),
+      apply: 'build'  // Only during build
+    },
+    {
+      ...devOnlyPlugin(),
+      apply: 'serve'  // Only during dev
+    }
+  ]
+})
+```
+
+Function form for more control:
+
+```ts
+{
+  ...myPlugin(),
+  apply(config, { command }) {
+    // Apply only on build but not for SSR
+    return command === 'build' && !config.build.ssr
+  }
+}
+```
+
+## Finding Plugins
+
+1. Check [Vite Features Guide](https://vite.dev/guide/features.html) - many use cases are built-in
+2. Official plugins in [Vite Plugins](https://vite.dev/plugins/)
+3. Community plugins in [awesome-vite](https://github.com/vitejs/awesome-vite#plugins)
+4. Search npm for `vite-plugin-*` or `rollup-plugin-*`
+
+## Official Plugins
+
+| Plugin | Purpose |
+|--------|---------|
+| `@vitejs/plugin-vue` | Vue 3 SFC support |
+| `@vitejs/plugin-vue-jsx` | Vue 3 JSX support |
+| `@vitejs/plugin-react` | React with Babel/Oxc |
+| `@vitejs/plugin-react-swc` | React with SWC |
+| `@vitejs/plugin-rsc` | React Server Components |
+| `@vitejs/plugin-legacy` | Legacy browser support |
+
+## Rollup/Rolldown Plugin Compatibility
+
+Many Rollup plugins work directly with Vite if they:
+- Don't use `moduleParsed` hook
+- Don't rely on Rolldown-specific options
+- Don't have strong coupling between bundle and output phases
+
+For build-only Rollup plugins:
+
+```ts
+export default defineConfig({
+  build: {
+    rolldownOptions: {
+      plugins: [rollupPluginForBuildOnly()]
+    }
+  }
+})
+```
+
+<!-- 
+Source references:
+- https://vite.dev/guide/using-plugins.html
+-->

.agents/skills/vite/references/features-assets.md

@@ -0,0 +1,138 @@
+---
+name: features-assets
+description: Static asset handling in Vite including imports, public directory, and URL handling
+---
+
+# Static Asset Handling
+
+## Importing Assets as URL
+
+```ts
+import imgUrl from './img.png'
+document.getElementById('hero-img').src = imgUrl
+// Dev: /src/img.png
+// Build: /assets/img.2d8efhg.png
+```
+
+Common image, media, and font types are detected automatically.
+
+## Import Queries
+
+### Explicit URL Import
+
+```ts
+import workletURL from './worklet.js?url'
+CSS.paintWorklet.addModule(workletURL)
+```
+
+### Import as String (Raw)
+
+```ts
+import shaderString from './shader.glsl?raw'
+```
+
+### Control Inlining
+
+```ts
+import imgUrl1 from './img.svg?no-inline'  // Never inline
+import imgUrl2 from './img.png?inline'      // Always inline as base64
+```
+
+## Asset Inlining
+
+Assets smaller than `assetsInlineLimit` (default 4KB) are inlined as base64:
+
+```ts
+export default defineConfig({
+  build: {
+    assetsInlineLimit: 4096,  // 4KB
+    // Or use callback for fine control
+    assetsInlineLimit: (filePath) => {
+      return !filePath.endsWith('.svg')
+    }
+  }
+})
+```
+
+## The `public` Directory
+
+Files in `public/` are:
+- Served at root path `/` during dev
+- Copied as-is to `dist/` root during build
+- Not processed or hashed
+
+```
+public/
+  favicon.ico  → /favicon.ico
+  robots.txt   → /robots.txt
+```
+
+Reference with absolute paths in source:
+
+```html
+<img src="/icon.png" />
+```
+
+Configure directory:
+
+```ts
+export default defineConfig({
+  publicDir: 'static'  // or false to disable
+})
+```
+
+## Extending Asset Types
+
+```ts
+export default defineConfig({
+  assetsInclude: ['**/*.gltf', '**/*.hdr']
+})
+```
+
+## Dynamic URLs with import.meta.url
+
+```ts
+// Works natively in modern browsers
+const imgUrl = new URL('./img.png', import.meta.url).href
+
+// Dynamic pattern (limited)
+function getImageUrl(name) {
+  return new URL(`./dir/${name}.png`, import.meta.url).href
+}
+```
+
+**Limitations:**
+- URL string must be static for build analysis
+- Does not work with SSR (different semantics in Node.js vs browser)
+
+## TypeScript Support
+
+Add `vite/client` to types for asset import recognition:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["vite/client"]
+  }
+}
+```
+
+## URL Handling in CSS
+
+```css
+.hero {
+  background: url('./img.png');  /* Processed and rebased */
+}
+```
+
+For dynamically constructed SVG URLs:
+
+```ts
+import imgUrl from './img.svg'
+element.style.background = `url("${imgUrl}")`  // Note double quotes
+```
+
+<!-- 
+Source references:
+- https://vite.dev/guide/assets.html
+-->

.agents/skills/vite/references/features-css.md

@@ -0,0 +1,215 @@
+---
+name: features-css
+description: CSS handling in Vite including modules, pre-processors, PostCSS, and Lightning CSS
+---
+
+# CSS Handling
+
+Vite provides rich CSS support with HMR, `@import` inlining, and automatic URL rebasing.
+
+## Basic CSS Import
+
+```ts
+import './styles.css'  // Injected into page with HMR support
+```
+
+## CSS Modules
+
+Files ending with `.module.css` are treated as CSS modules:
+
+```css
+/* example.module.css */
+.red {
+  color: red;
+}
+```
+
+```ts
+import classes from './example.module.css'
+element.className = classes.red
+```
+
+### Named Imports with camelCase
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  css: {
+    modules: {
+      localsConvention: 'camelCaseOnly'
+    }
+  }
+})
+```
+
+```ts
+// .apply-color -> applyColor
+import { applyColor } from './example.module.css'
+```
+
+## CSS Pre-processors
+
+Install the pre-processor, no Vite plugin needed:
+
+```bash
+# Sass (sass-embedded recommended for performance)
+npm add -D sass-embedded
+
+# Less
+npm add -D less
+
+# Stylus
+npm add -D stylus
+```
+
+Use by file extension:
+
+```ts
+import './styles.scss'
+import './styles.less'
+import './styles.styl'
+```
+
+### Pre-processor Options
+
+```ts
+export default defineConfig({
+  css: {
+    preprocessorOptions: {
+      scss: {
+        additionalData: `$injectedColor: orange;`,
+        importers: [/* ... */]
+      },
+      less: {
+        math: 'parens-division'
+      }
+    },
+    preprocessorMaxWorkers: true  // Use multiple threads
+  }
+})
+```
+
+### Combined with CSS Modules
+
+```ts
+import styles from './component.module.scss'
+```
+
+## PostCSS
+
+Automatically applied if `postcss.config.js` exists:
+
+```js
+// postcss.config.js
+export default {
+  plugins: [
+    require('postcss-nesting'),
+    require('autoprefixer')
+  ]
+}
+```
+
+Or configure inline:
+
+```ts
+export default defineConfig({
+  css: {
+    postcss: {
+      plugins: [
+        postcssNesting(),
+        autoprefixer()
+      ]
+    }
+  }
+})
+```
+
+## Lightning CSS
+
+Experimental faster CSS processing:
+
+```bash
+npm add -D lightningcss
+```
+
+```ts
+export default defineConfig({
+  css: {
+    transformer: 'lightningcss',
+    lightningcss: {
+      targets: {
+        chrome: 111
+      },
+      cssModules: {
+        // Lightning CSS modules config
+      }
+    }
+  }
+})
+```
+
+Use Lightning CSS for minification only:
+
+```ts
+export default defineConfig({
+  build: {
+    cssMinify: 'lightningcss'
+  }
+})
+```
+
+## Disable CSS Injection
+
+Import CSS as string without injecting:
+
+```ts
+import styles from './styles.css?inline'  // Returns CSS string, not injected
+```
+
+## Source Maps
+
+Enable CSS source maps in development:
+
+```ts
+export default defineConfig({
+  css: {
+    devSourcemap: true
+  }
+})
+```
+
+## CSS Code Splitting
+
+By default, CSS is extracted per async chunk. Disable to get single CSS file:
+
+```ts
+export default defineConfig({
+  build: {
+    cssCodeSplit: false  // Single CSS file for entire app
+  }
+})
+```
+
+## CSS Target
+
+Set different browser target for CSS:
+
+```ts
+export default defineConfig({
+  build: {
+    cssTarget: 'chrome61'  // For Android WeChat WebView
+  }
+})
+```
+
+## @import and URL Handling
+
+- `@import` statements are inlined automatically
+- Vite aliases work in `@import`
+- `url()` references are rebased for correctness
+- Works across Sass/Less files in different directories
+
+<!-- 
+Source references:
+- https://vite.dev/guide/features.html#css
+-->

.agents/skills/vite/references/features-dep-bundling.md

@@ -0,0 +1,148 @@
+---
+name: features-dep-bundling
+description: Dependency pre-bundling configuration and caching
+---
+
+# Dependency Pre-Bundling
+
+Vite pre-bundles dependencies on first run for faster dev server startup.
+
+## Why Pre-Bundling
+
+1. **CommonJS/UMD to ESM** - Convert non-ESM dependencies
+2. **Performance** - Bundle many internal modules into single file (e.g., lodash-es has 600+ modules)
+
+```ts
+// Works thanks to smart import analysis
+import React, { useState } from 'react'
+```
+
+## Automatic Discovery
+
+Vite crawls source code to find bare imports and pre-bundles them with Rolldown.
+
+New dependencies discovered after server start trigger re-bundling.
+
+## Including Dependencies
+
+Force pre-bundling for dependencies not auto-discovered:
+
+```ts
+export default defineConfig({
+  optimizeDeps: {
+    include: [
+      'some-package',
+      'another-package/nested'  // Deep imports
+    ]
+  }
+})
+```
+
+**When to include:**
+- Dynamically imported (via plugin transform)
+- Large dependencies with many internal modules
+- CommonJS dependencies
+
+## Excluding Dependencies
+
+Skip pre-bundling for small ESM-only dependencies:
+
+```ts
+export default defineConfig({
+  optimizeDeps: {
+    exclude: ['small-esm-dep']
+  }
+})
+```
+
+## Monorepo Linked Dependencies
+
+Linked packages are treated as source code by default. If not ESM:
+
+```ts
+export default defineConfig({
+  optimizeDeps: {
+    include: ['linked-dep']
+  }
+})
+```
+
+Restart with `--force` after making changes to linked deps.
+
+## Custom Rolldown Options
+
+```ts
+export default defineConfig({
+  optimizeDeps: {
+    rolldownOptions: {
+      plugins: [/* Rolldown plugins */],
+      // Other Rolldown options
+    }
+  }
+})
+```
+
+## Caching
+
+### File System Cache
+
+Located in `node_modules/.vite`. Re-runs when:
+
+- Package lockfile changes (`package-lock.json`, `pnpm-lock.yaml`, etc.)
+- Patches folder modified
+- `vite.config.js` changes
+- `NODE_ENV` changes
+
+Force re-bundle:
+
+```bash
+vite --force
+# Or delete node_modules/.vite
+```
+
+### Browser Cache
+
+Pre-bundled deps are cached with `max-age=31536000,immutable`.
+
+To debug dependencies with local edits:
+
+1. Disable cache in browser DevTools Network tab
+2. Restart Vite with `--force`
+3. Reload page
+
+## Entries
+
+Specify custom entry points for discovery:
+
+```ts
+export default defineConfig({
+  optimizeDeps: {
+    entries: [
+      'src/main.ts',
+      'src/other-entry.ts'
+    ]
+  }
+})
+```
+
+By default, all HTML files are used as entries.
+
+## esbuildOptions (Deprecated)
+
+Use `rolldownOptions` instead:
+
+```ts
+export default defineConfig({
+  optimizeDeps: {
+    // Deprecated
+    esbuildOptions: {},
+    // Use instead
+    rolldownOptions: {}
+  }
+})
+```
+
+<!-- 
+Source references:
+- https://vite.dev/guide/dep-pre-bundling.html
+-->

.agents/skills/vite/references/features-env.md

@@ -0,0 +1,161 @@
+---
+name: features-env
+description: Environment variables, .env files, and modes in Vite
+---
+
+# Environment Variables and Modes
+
+## Built-in Constants
+
+Available via `import.meta.env`:
+
+| Constant | Description |
+|----------|-------------|
+| `import.meta.env.MODE` | App mode (`'development'` or `'production'`) |
+| `import.meta.env.BASE_URL` | Base URL from `base` config |
+| `import.meta.env.PROD` | `true` in production |
+| `import.meta.env.DEV` | `true` in development |
+| `import.meta.env.SSR` | `true` in server-side rendering |
+
+```ts
+if (import.meta.env.DEV) {
+  console.log('Development mode')
+  // Tree-shaken in production
+}
+```
+
+## Custom Environment Variables
+
+Only variables prefixed with `VITE_` are exposed to client code:
+
+```bash
+# .env
+VITE_API_URL=https://api.example.com
+DB_PASSWORD=secret  # NOT exposed to client
+```
+
+```ts
+console.log(import.meta.env.VITE_API_URL)  // "https://api.example.com"
+console.log(import.meta.env.DB_PASSWORD)   // undefined
+```
+
+### Custom Prefix
+
+```ts
+export default defineConfig({
+  envPrefix: ['VITE_', 'APP_']  // Expose VITE_* and APP_*
+})
+```
+
+## .env Files
+
+Load order (later has higher priority):
+
+```
+.env                # Always loaded
+.env.local          # Always loaded, gitignored
+.env.[mode]         # Only in specified mode
+.env.[mode].local   # Only in specified mode, gitignored
+```
+
+### Variable Expansion
+
+```bash
+# .env
+KEY=123
+EXPANDED=test$KEY   # test123
+ESCAPED=test\$foo   # test$foo (escaped)
+```
+
+## Modes
+
+```bash
+# Development mode (default for dev)
+vite
+
+# Production mode (default for build)
+vite build
+
+# Custom mode
+vite build --mode staging
+```
+
+Create mode-specific env file:
+
+```bash
+# .env.staging
+VITE_APP_TITLE=My App (staging)
+NODE_ENV=production  # Still production build
+```
+
+### NODE_ENV vs Mode
+
+| Command | NODE_ENV | Mode |
+|---------|----------|------|
+| `vite build` | `production` | `production` |
+| `vite build --mode development` | `production` | `development` |
+| `NODE_ENV=development vite build` | `development` | `production` |
+
+## TypeScript IntelliSense
+
+Create type declarations for custom env variables:
+
+```ts
+// vite-env.d.ts
+interface ImportMetaEnv {
+  readonly VITE_APP_TITLE: string
+  readonly VITE_API_URL: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}
+```
+
+For strict typing (disallow unknown keys):
+
+```ts
+interface ViteTypeOptions {
+  strictImportMetaEnv: unknown
+}
+```
+
+## HTML Replacement
+
+Use `%VARIABLE%` syntax in HTML:
+
+```html
+<title>%VITE_APP_TITLE%</title>
+<p>Mode: %MODE%</p>
+```
+
+Non-existent variables are left as-is (not replaced with `undefined`).
+
+## Loading Env in Config
+
+Env vars are NOT available in `vite.config.ts` automatically:
+
+```ts
+import { defineConfig, loadEnv } from 'vite'
+
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd(), '')  // '' loads all vars
+  
+  return {
+    define: {
+      __APP_ENV__: JSON.stringify(env.APP_ENV)
+    }
+  }
+})
+```
+
+## Security Notes
+
+- Add `*.local` to `.gitignore`
+- `VITE_*` variables end up in client bundle - no secrets
+- Never set `envPrefix` to `''` (exposes everything)
+
+<!-- 
+Source references:
+- https://vite.dev/guide/env-and-mode.html
+-->

.agents/skills/vite/references/features-glob-import.md

@@ -0,0 +1,161 @@
+---
+name: features-glob-import
+description: Vite's import.meta.glob for batch importing modules and dynamic imports
+---
+
+# Glob Import
+
+## Basic Usage
+
+Import multiple modules using glob patterns:
+
+```ts
+const modules = import.meta.glob('./dir/*.js')
+// Transformed to:
+// {
+//   './dir/foo.js': () => import('./dir/foo.js'),
+//   './dir/bar.js': () => import('./dir/bar.js'),
+// }
+```
+
+Iterate and load:
+
+```ts
+for (const path in modules) {
+  modules[path]().then((mod) => {
+    console.log(path, mod)
+  })
+}
+```
+
+## Eager Loading
+
+Load all modules immediately (no dynamic import):
+
+```ts
+const modules = import.meta.glob('./dir/*.js', { eager: true })
+// Transformed to:
+// import * as __glob_0 from './dir/foo.js'
+// import * as __glob_1 from './dir/bar.js'
+// const modules = {
+//   './dir/foo.js': __glob_0,
+//   './dir/bar.js': __glob_1,
+// }
+```
+
+## Multiple Patterns
+
+```ts
+const modules = import.meta.glob([
+  './dir/*.js',
+  './another/*.js'
+])
+```
+
+## Negative Patterns
+
+Exclude files with `!` prefix:
+
+```ts
+const modules = import.meta.glob([
+  './dir/*.js',
+  '!**/bar.js'  // Exclude bar.js
+])
+```
+
+## Named Imports
+
+Import specific exports for tree-shaking:
+
+```ts
+const modules = import.meta.glob('./dir/*.js', {
+  import: 'setup'
+})
+// './dir/foo.js': () => import('./dir/foo.js').then(m => m.setup)
+```
+
+Import default export:
+
+```ts
+const modules = import.meta.glob('./dir/*.js', {
+  import: 'default',
+  eager: true
+})
+```
+
+## Custom Queries
+
+Import as raw strings or URLs:
+
+```ts
+const moduleStrings = import.meta.glob('./dir/*.svg', {
+  query: '?raw',
+  import: 'default'
+})
+
+const moduleUrls = import.meta.glob('./dir/*.svg', {
+  query: '?url',
+  import: 'default'
+})
+```
+
+Custom queries for plugins:
+
+```ts
+const modules = import.meta.glob('./dir/*.js', {
+  query: { foo: 'bar', bar: true }
+})
+```
+
+## Base Path
+
+Change the base path for imports:
+
+```ts
+const modules = import.meta.glob('./**/*.js', {
+  base: './base'
+})
+// Keys: './dir/foo.js'
+// Imports: './base/dir/foo.js'
+```
+
+## Important Caveats
+
+1. **Vite-only feature** - Not a web standard
+2. **Patterns must be literals** - Cannot use variables
+3. **Relative or absolute** - Must start with `./`, `/`, or use an alias
+4. **Glob matching** - Uses [tinyglobby](https://github.com/SuperchupuDev/tinyglobby)
+
+## Dynamic Import with Variables
+
+Limited dynamic import support:
+
+```ts
+const module = await import(`./dir/${file}.js`)
+```
+
+**Rules:**
+- Must start with `./` or `../`
+- Must end with file extension
+- Variable represents only one level (no `foo/bar`)
+- Own directory needs filename pattern: `./prefix-${foo}.js` not `./${foo}.js`
+
+## Practical Example: Loading Route Components
+
+```ts
+// Lazy load all page components
+const pages = import.meta.glob('./pages/*.vue')
+
+const routes = Object.keys(pages).map((path) => {
+  const name = path.match(/\.\/pages\/(.*)\.vue$/)[1]
+  return {
+    path: `/${name.toLowerCase()}`,
+    component: pages[path]  // Lazy loaded
+  }
+})
+```
+
+<!-- 
+Source references:
+- https://vite.dev/guide/features.html#glob-import
+-->

.agents/skills/vite/references/features-hmr.md

@@ -0,0 +1,200 @@
+---
+name: features-hmr
+description: Vite's Hot Module Replacement (HMR) client API
+---
+
+# HMR API
+
+The HMR API is exposed via `import.meta.hot`. Primarily for framework and tooling authors.
+
+## Conditional Guard
+
+Always guard HMR code for tree-shaking in production:
+
+```ts
+if (import.meta.hot) {
+  // HMR code
+}
+```
+
+## TypeScript Support
+
+Add to `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["vite/client"]
+  }
+}
+```
+
+## Self-Accepting Module
+
+Module handles its own updates:
+
+```ts
+export const count = 1
+
+if (import.meta.hot) {
+  import.meta.hot.accept((newModule) => {
+    if (newModule) {
+      console.log('updated: count is now', newModule.count)
+    }
+  })
+}
+```
+
+## Accept Dependency Updates
+
+React to changes in dependencies without self-reload:
+
+```ts
+import { foo } from './foo.js'
+
+foo()
+
+if (import.meta.hot) {
+  // Single dependency
+  import.meta.hot.accept('./foo.js', (newFoo) => {
+    newFoo?.foo()
+  })
+  
+  // Multiple dependencies
+  import.meta.hot.accept(
+    ['./foo.js', './bar.js'],
+    ([newFooModule, newBarModule]) => {
+      // Handle updates
+    }
+  )
+}
+```
+
+## Cleanup on Update
+
+Clean up side effects before module is replaced:
+
+```ts
+function setupSideEffect() {
+  const interval = setInterval(() => {}, 1000)
+  return interval
+}
+
+const interval = setupSideEffect()
+
+if (import.meta.hot) {
+  import.meta.hot.dispose((data) => {
+    clearInterval(interval)
+  })
+}
+```
+
+## Prune Callback
+
+Called when module is no longer imported:
+
+```ts
+if (import.meta.hot) {
+  import.meta.hot.prune((data) => {
+    // Cleanup when module is removed from page
+  })
+}
+```
+
+## Persistent Data
+
+Pass data between module instances:
+
+```ts
+if (import.meta.hot) {
+  // Mutate properties, don't reassign data itself
+  import.meta.hot.data.count = (import.meta.hot.data.count || 0) + 1
+}
+```
+
+## Invalidate
+
+Force propagation to importers:
+
+```ts
+if (import.meta.hot) {
+  import.meta.hot.accept((module) => {
+    if (cannotHandleUpdate(module)) {
+      import.meta.hot.invalidate()  // Propagate to importers
+    }
+  })
+}
+```
+
+## HMR Events
+
+Listen to built-in events:
+
+```ts
+if (import.meta.hot) {
+  import.meta.hot.on('vite:beforeUpdate', (payload) => {
+    console.log('Update incoming')
+  })
+  
+  import.meta.hot.on('vite:afterUpdate', (payload) => {
+    console.log('Update applied')
+  })
+  
+  import.meta.hot.on('vite:beforeFullReload', () => {
+    console.log('Full reload')
+  })
+  
+  import.meta.hot.on('vite:error', (error) => {
+    console.error('HMR error', error)
+  })
+  
+  import.meta.hot.on('vite:ws:connect', () => {
+    console.log('WebSocket connected')
+  })
+  
+  import.meta.hot.on('vite:ws:disconnect', () => {
+    console.log('WebSocket disconnected')
+  })
+}
+```
+
+## Custom Events
+
+Send events to server:
+
+```ts
+// Client
+if (import.meta.hot) {
+  import.meta.hot.send('my:event', { msg: 'Hello from client' })
+}
+```
+
+Receive from server:
+
+```ts
+// Client
+if (import.meta.hot) {
+  import.meta.hot.on('my:response', (data) => {
+    console.log(data.msg)
+  })
+}
+```
+
+## TypeScript for Custom Events
+
+```ts
+// events.d.ts
+import 'vite/types/customEvent.d.ts'
+
+declare module 'vite/types/customEvent.d.ts' {
+  interface CustomEventMap {
+    'my:event': { msg: string }
+    'my:response': { msg: string }
+  }
+}
+```
+
+<!-- 
+Source references:
+- https://vite.dev/guide/api-hmr.html
+-->

.agents/skills/vite/references/features-workers.md

@@ -0,0 +1,115 @@
+---
+name: features-workers
+description: Web Worker support in Vite
+---
+
+# Web Workers
+
+## Constructor Syntax (Recommended)
+
+Standard Web Worker creation:
+
+```ts
+const worker = new Worker(new URL('./worker.js', import.meta.url))
+```
+
+Module worker:
+
+```ts
+const worker = new Worker(new URL('./worker.js', import.meta.url), {
+  type: 'module'
+})
+```
+
+Shared Worker:
+
+```ts
+const sharedWorker = new SharedWorker(
+  new URL('./shared-worker.js', import.meta.url)
+)
+```
+
+**Note:** The `new URL()` must be used directly inside `new Worker()` for detection.
+
+## Query Suffix Syntax
+
+Import with `?worker` suffix:
+
+```ts
+import MyWorker from './worker?worker'
+
+const worker = new MyWorker()
+```
+
+Shared worker:
+
+```ts
+import MySharedWorker from './worker?sharedworker'
+
+const worker = new MySharedWorker()
+```
+
+### Inline Worker
+
+Inline as base64 string (no separate chunk):
+
+```ts
+import MyWorker from './worker?worker&inline'
+
+const worker = new MyWorker()
+```
+
+### Worker URL Only
+
+Get URL instead of constructor:
+
+```ts
+import workerUrl from './worker?worker&url'
+```
+
+## Worker Script
+
+Workers can use ESM `import` statements:
+
+```ts
+// worker.js
+import { heavyComputation } from './utils'
+
+self.onmessage = (e) => {
+  const result = heavyComputation(e.data)
+  self.postMessage(result)
+}
+```
+
+## Worker Options
+
+Configure worker bundling:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  worker: {
+    format: 'es',  // or 'iife'
+    plugins: () => [/* worker-specific plugins */],
+    rollupOptions: {
+      // Rollup options for worker bundle
+    }
+  }
+})
+```
+
+## WebAssembly in Workers
+
+```ts
+// worker.js
+import init from './module.wasm?init'
+
+init().then((instance) => {
+  instance.exports.compute()
+})
+```
+
+<!-- 
+Source references:
+- https://vite.dev/guide/features.html#web-workers
+-->

.agents/skills/vue-best-practices/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 hyf0
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

.agents/skills/vue-best-practices/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: vue-best-practices
+description: Vue 3 and Vue.js best practices for TypeScript, vue-tsc, and Volar. This skill should be used when writing, reviewing, or refactoring Vue components to ensure correct typing patterns. Triggers on tasks involving Vue components, props extraction, wrapper components, template type checking, or Volar configuration.
+license: MIT
+metadata:
+  author: hyf0
+  version: "8.0.0"
+---
+
+## Capability Rules
+
+| Rule | Keywords | Description |
+|------|----------|-------------|
+| [extract-component-props](rules/extract-component-props.md) | get props type, wrapper component, extend props, inherit props, ComponentProps | Extract types from .vue components |
+| [vue-tsc-strict-templates](rules/vue-tsc-strict-templates.md) | undefined component, template error, strictTemplates | Catch undefined components in templates |
+| [fallthrough-attributes](rules/fallthrough-attributes.md) | fallthrough, $attrs, wrapper component | Type-check fallthrough attributes |
+| [strict-css-modules](rules/strict-css-modules.md) | css modules, $style, typo | Catch CSS module class typos |
+| [data-attributes-config](rules/data-attributes-config.md) | data-*, strictTemplates, attribute | Allow data-* attributes |
+| [volar-3-breaking-changes](rules/volar-3-breaking-changes.md) | volar, vue-language-server, editor | Fix Volar 3.0 upgrade issues |
+| [module-resolution-bundler](rules/module-resolution-bundler.md) | cannot find module, @vue/tsconfig, moduleResolution | Fix module resolution errors |
+| [define-model-update-event](rules/define-model-update-event.md) | defineModel, update event, undefined | Fix model update errors |
+| [with-defaults-union-types](rules/with-defaults-union-types.md) | withDefaults, union type, default | Fix union type defaults |
+| [deep-watch-numeric](rules/deep-watch-numeric.md) | watch, deep, array, Vue 3.5 | Efficient array watching |
+| [vue-directive-comments](rules/vue-directive-comments.md) | @vue-ignore, @vue-skip, template | Control template type checking |
+| [vue-router-typed-params](rules/vue-router-typed-params.md) | route params, typed router, unplugin | Fix route params typing |
+
+## Efficiency Rules
+
+| Rule | Keywords | Description |
+|------|----------|-------------|
+| [hmr-vue-ssr](rules/hmr-vue-ssr.md) | hmr, ssr, hot reload | Fix HMR in SSR apps |
+| [pinia-store-mocking](rules/pinia-store-mocking.md) | pinia, mock, vitest, store | Mock Pinia stores |
+
+## Reference
+
+- [Vue Language Tools](https://github.com/vuejs/language-tools)
+- [vue-component-type-helpers](https://github.com/vuejs/language-tools/tree/master/packages/component-type-helpers)
+- [Vue 3 Documentation](https://vuejs.org/)

.agents/skills/vue-best-practices/SYNC.md

@@ -0,0 +1,5 @@
+# Sync Info
+
+- **Source:** `vendor/vue-best-practices/skills/vue-best-practices`
+- **Git SHA:** `ee0ceda40b7fabeb0713caf8b4db5ea438069fb5`
+- **Synced:** 2026-01-28

.agents/skills/vue-best-practices/rules/codeactions-save-performance.md

@@ -0,0 +1,79 @@
+---
+title: Fix Slow Save Times with Code Actions Setting
+impact: HIGH
+impactDescription: fixes 30-60 second save delays in large Vue projects
+type: capability
+tags: performance, save-time, vscode, code-actions, volar
+---
+
+# Fix Slow Save Times with Code Actions Setting
+
+**Impact: HIGH** - fixes 30-60 second save delays in large Vue projects
+
+In large Vue projects, saving files can take 30-60+ seconds due to VSCode's code actions triggering expensive TypeScript state synchronization.
+
+## Problem
+
+Symptoms:
+- Save operation takes 30+ seconds
+- Editor becomes unresponsive during save
+- CPU spikes when saving Vue files
+- Happens more in larger projects
+
+## Root Cause
+
+VSCode emits document change events multiple times during save cycles. Each event triggers Volar to synchronize with TypeScript, causing expensive re-computation.
+
+## Solution
+
+Disable code actions or limit their timeout:
+
+**Option 1: Disable code actions (fastest)**
+```json
+// .vscode/settings.json
+{
+  "vue.codeActions.enabled": false
+}
+```
+
+**Option 2: Limit code action time**
+```json
+// .vscode/settings.json
+{
+  "vue.codeActions.savingTimeLimit": 1000
+}
+```
+
+**Option 3: Disable specific code actions**
+```json
+// .vscode/settings.json
+{
+  "vue.codeActions.enabled": true,
+  "editor.codeActionsOnSave": {
+    "source.organizeImports": "never"
+  }
+}
+```
+
+## VSCode Version Requirement
+
+VSCode 1.81.0+ includes fixes that reduce save time issues. Upgrade if using an older version.
+
+## Additional Optimizations
+
+```json
+// .vscode/settings.json
+{
+  "vue.codeActions.enabled": false,
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {},
+  "[vue]": {
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "Vue.volar"
+  }
+}
+```
+
+## Reference
+
+- [Vue Language Tools Discussion #2740](https://github.com/vuejs/language-tools/discussions/2740)

.agents/skills/vue-best-practices/rules/data-attributes-config.md

@@ -0,0 +1,74 @@
+---
+title: Allow Data Attributes with Strict Templates
+impact: MEDIUM
+impactDescription: fixes data-testid and data-* attribute errors in strict mode
+type: capability
+tags: dataAttributes, vueCompilerOptions, strictTemplates, data-testid, testing
+---
+
+# Allow Data Attributes with Strict Templates
+
+**Impact: MEDIUM** - fixes data-testid and data-* attribute errors in strict mode
+
+With `strictTemplates` enabled, `data-*` attributes on components cause type errors. Use the `dataAttributes` option to allow specific patterns.
+
+## Problem
+
+```vue
+<template>
+  <!-- Error: Property 'data-testid' does not exist on type... -->
+  <MyComponent data-testid="submit-button" />
+
+  <!-- Error: Property 'data-cy' does not exist on type... -->
+  <MyComponent data-cy="login-form" />
+</template>
+```
+
+## Solution
+
+Configure `dataAttributes` to allow specific patterns:
+
+```json
+// tsconfig.json or tsconfig.app.json
+{
+  "vueCompilerOptions": {
+    "strictTemplates": true,
+    "dataAttributes": ["data-*"]
+  }
+}
+```
+
+Now all `data-*` attributes are allowed on any component.
+
+## Specific Patterns
+
+You can be more selective:
+
+```json
+{
+  "vueCompilerOptions": {
+    "dataAttributes": [
+      "data-testid",
+      "data-cy",
+      "data-test-*"
+    ]
+  }
+}
+```
+
+This only allows the specified patterns, not all data attributes.
+
+## Common Testing Attributes
+
+For testing libraries, allow their specific attributes:
+
+| Library | Attribute | Pattern |
+|---------|-----------|---------|
+| Testing Library | `data-testid` | `"data-testid"` |
+| Cypress | `data-cy` | `"data-cy"` |
+| Playwright | `data-testid` | `"data-testid"` |
+| Generic | All data attributes | `"data-*"` |
+
+## Reference
+
+- [Vue Language Tools Wiki - Vue Compiler Options](https://github.com/vuejs/language-tools/wiki/Vue-Compiler-Options)

.agents/skills/vue-best-practices/rules/deep-watch-numeric.md

@@ -0,0 +1,97 @@
+---
+title: Vue 3.5+ Deep Watch Numeric Depth
+impact: MEDIUM
+impactDescription: enables efficient array mutation watching with numeric deep option
+type: capability
+tags: watch, deep, vue-3.5, array, mutation, performance
+---
+
+# Vue 3.5+ Deep Watch Numeric Depth
+
+**Impact: MEDIUM** - enables efficient array mutation watching with numeric deep option
+
+Vue 3.5 introduced `deep: number` for watch depth control. This allows watching array mutations without the performance cost of deep traversal.
+
+## Symptoms
+
+- Array mutations not triggering watch callback
+- Deep watch causing performance issues on large nested objects
+- Unaware of new Vue 3.5 feature
+
+> **Note:** TypeScript error "Type 'number' is not assignable to type 'boolean'" no longer occurs with Vue 3.5+ and current TypeScript versions. The types now correctly support numeric `deep` values.
+
+## The Feature
+
+```typescript
+// Vue 3.5+ only
+watch(items, (newVal) => {
+  // Triggered on array mutations (push, pop, splice, etc.)
+}, { deep: 1 })
+```
+
+| deep value | Behavior |
+|------------|----------|
+| `true` | Full recursive traversal (original behavior) |
+| `false` | Only reference changes |
+| `1` | One level deep - array mutations, not nested objects |
+| `2` | Two levels deep |
+| `n` | N levels deep |
+
+## Fix
+
+**Step 1: Ensure Vue 3.5+**
+```bash
+npm install vue@^3.5.0
+```
+
+**Step 2: Use numeric depth**
+```typescript
+import { watch, ref } from 'vue'
+
+const items = ref([{ id: 1, data: { nested: 'value' } }])
+
+// Watch array mutations only (push, pop, etc.)
+watch(items, (newItems) => {
+  console.log('Array mutated')
+}, { deep: 1 })
+
+// Won't trigger on: items.value[0].data.nested = 'new'
+// Will trigger on: items.value.push(newItem)
+```
+
+## Performance Comparison
+
+```typescript
+const largeNestedData = ref({ /* deeply nested structure */ })
+
+// SLOW - traverses entire structure
+watch(largeNestedData, handler, { deep: true })
+
+// FAST - only watches top-level changes
+watch(largeNestedData, handler, { deep: 1 })
+
+// FASTEST - only reference changes
+watch(largeNestedData, handler, { deep: false })
+```
+
+## Alternative: watchEffect for Selective Tracking
+
+```typescript
+// Only tracks properties actually accessed
+watchEffect(() => {
+  // Only re-runs when items.value.length or first item changes
+  console.log(items.value.length, items.value[0]?.id)
+})
+```
+
+## TypeScript Note
+
+If TypeScript complains about numeric deep, ensure:
+1. Vue version is 3.5+
+2. TypeScript version is current (types are included with `vue` package)
+3. tsconfig targets correct node_modules types
+
+## Reference
+
+- [Vue Watchers Docs](https://vuejs.org/guide/essentials/watchers.html)
+- [Vue 3.5 Release Notes](https://blog.vuejs.org/posts/vue-3-5)

.agents/skills/vue-best-practices/rules/define-model-update-event.md

@@ -0,0 +1,79 @@
+---
+title: defineModel Fires Update Event with Undefined
+impact: MEDIUM
+impactDescription: fixes runtime errors from unexpected undefined in model updates
+type: capability
+tags: defineModel, v-model, update-event, undefined, vue-3.5
+---
+
+# defineModel Fires Update Event with Undefined
+
+**Impact: MEDIUM** - fixes runtime errors from unexpected undefined in model updates
+
+> **Version Note:** This issue may be resolved in Vue 3.5+. Testing with Vue 3.5.26 could not reproduce the double emission with `undefined`. If you're on Vue 3.5+, verify the issue exists in your specific scenario before applying workarounds.
+
+Components using `defineModel` may fire the `@update:model-value` event with `undefined` in certain edge cases. TypeScript types don't always reflect this behavior, potentially causing runtime errors when the parent expects a non-nullable value.
+
+## Symptoms
+
+- Parent component receives `undefined` unexpectedly
+- Runtime error: "Cannot read property of undefined"
+- Type mismatch between expected `T` and received `T | undefined`
+- Issue appears when clearing/resetting the model value
+
+## Root Cause
+
+`defineModel` returns `Ref<T | undefined>` by default, even when `T` is non-nullable. The update event can fire with `undefined` when:
+- Component unmounts
+- Model is explicitly cleared
+- Internal state resets
+
+## Fix
+
+**Option 1: Use required option (Vue 3.5+)**
+```typescript
+// Returns Ref<Item> instead of Ref<Item | undefined>
+const model = defineModel<Item>({ required: true })
+```
+
+**Option 2: Type parent handler to accept undefined**
+```vue
+<template>
+  <MyComponent
+    v-model="item"
+    @update:model-value="handleUpdate"
+  />
+</template>
+
+<script setup lang="ts">
+// Handle both value and undefined
+const handleUpdate = (value: Item | undefined) => {
+  if (value !== undefined) {
+    item.value = value
+  }
+}
+</script>
+```
+
+**Option 3: Use default value in defineModel**
+```typescript
+const model = defineModel<string>({ default: '' })
+```
+
+## Type Declaration Pattern
+
+```typescript
+// In child component
+interface Props {
+  modelValue: Item
+}
+const model = defineModel<Item>({ required: true })
+
+// Emits will be typed as (value: Item) not (value: Item | undefined)
+```
+
+## Reference
+
+- [vuejs/core#12817](https://github.com/vuejs/core/issues/12817)
+- [vuejs/core#10103](https://github.com/vuejs/core/issues/10103)
+- [defineModel docs](https://vuejs.org/api/sfc-script-setup.html#definemodel)

.agents/skills/vue-best-practices/rules/duplicate-plugin-detection.md

@@ -0,0 +1,102 @@
+---
+title: Duplicate Vue Plugin Detection
+impact: MEDIUM
+impactDescription: fixes cryptic build errors from Vue plugin registered twice
+type: capability
+tags: vite, plugin, vue, duplicate, config, inline
+---
+
+# Duplicate Vue Plugin Detection
+
+**Impact: MEDIUM** - fixes cryptic build errors from Vue plugin registered twice
+
+When using Vite's JavaScript API, if the Vue plugin is loaded in `vite.config.js` and specified again in `inlineConfig`, it gets registered twice, causing cryptic build errors.
+
+## Symptoms
+
+- Build produces unexpected output or fails silently
+- "Cannot read property of undefined" during build
+- Different build behavior between CLI and JavaScript API
+- Vue components render incorrectly after build
+
+## Root Cause
+
+Vite doesn't deduplicate plugins by name when merging configs. The Vue plugin's internal state gets corrupted when registered twice.
+
+## Fix
+
+**Option 1: Use configFile: false with inline plugins**
+```typescript
+import { build } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+await build({
+  configFile: false,  // Don't load vite.config.js
+  plugins: [vue()],
+  // ... rest of config
+})
+```
+
+**Option 2: Don't specify plugins in inlineConfig**
+```typescript
+// vite.config.js already has vue plugin
+import { build } from 'vite'
+
+await build({
+  // Don't add vue plugin here - it's in vite.config.js
+  root: './src',
+  build: { outDir: '../dist' }
+})
+```
+
+**Option 3: Filter out Vue plugin before merging**
+```typescript
+import { build, loadConfigFromFile } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+const { config } = await loadConfigFromFile({ command: 'build', mode: 'production' })
+
+// Remove existing Vue plugin
+const filteredPlugins = config.plugins?.filter(
+  p => !p || (Array.isArray(p) ? false : p.name !== 'vite:vue')
+) || []
+
+await build({
+  ...config,
+  plugins: [...filteredPlugins, vue({ /* your options */ })]
+})
+```
+
+## Detection Script
+
+Add this to debug plugin registration:
+```typescript
+// vite.config.ts
+export default defineConfig({
+  plugins: [
+    vue(),
+    {
+      name: 'debug-plugins',
+      configResolved(config) {
+        const vuePlugins = config.plugins.filter(p => p.name?.includes('vue'))
+        if (vuePlugins.length > 1) {
+          console.warn('WARNING: Multiple Vue plugins detected:', vuePlugins.map(p => p.name))
+        }
+      }
+    }
+  ]
+})
+```
+
+## Common Scenarios
+
+| Scenario | Solution |
+|----------|----------|
+| Using `vite.createServer()` | Use `configFile: false` |
+| Build script with custom config | Don't duplicate plugins |
+| Monorepo with shared config | Check for plugin inheritance |
+
+## Reference
+
+- [Vite Issue #5335](https://github.com/vitejs/vite/issues/5335)
+- [Vite JavaScript API](https://vite.dev/guide/api-javascript.html)

.agents/skills/vue-best-practices/rules/extract-component-props.md

@@ -0,0 +1,57 @@
+---
+title: Extract Component Props
+impact: HIGH
+impactDescription: extract props, emits, slots types from .vue components
+type: capability
+tags: typescript, props, emits, slots, vue-component-type-helpers, wrapper, ComponentProps
+---
+
+# Extract Component Props
+
+**Impact: HIGH** - extract props, emits, slots types from .vue components
+
+Use `vue-component-type-helpers` to extract types from `.vue` components:
+
+```bash
+npm install -D vue-component-type-helpers
+```
+
+```typescript
+import type { ComponentProps, ComponentEmit, ComponentSlots, ComponentExposed } from 'vue-component-type-helpers'
+import MyButton from './MyButton.vue'
+
+type Props = ComponentProps<typeof MyButton>
+type Emits = ComponentEmit<typeof MyButton>
+type Slots = ComponentSlots<typeof MyButton>
+type Exposed = ComponentExposed<typeof MyButton>
+```
+
+## Wrapper Component Pattern
+
+```typescript
+import type { ComponentProps } from 'vue-component-type-helpers'
+import BaseButton from './BaseButton.vue'
+
+type BaseProps = ComponentProps<typeof BaseButton>
+
+interface Props extends BaseProps {
+  size: 'sm' | 'md' | 'lg'
+}
+
+defineProps<Props>()
+```
+
+## Do NOT Use
+
+```typescript
+// ❌ Includes Vue internal properties (onUpdate:*, class, style, etc.)
+type Props = InstanceType<typeof MyButton>['$props']
+```
+
+## Note
+
+Vue's built-in `ExtractPropTypes` is for runtime props objects (`props: { foo: String }`), not for `.vue` components.
+
+## Reference
+
+- [vue-component-type-helpers](https://github.com/vuejs/language-tools/tree/master/packages/component-type-helpers)

.agents/skills/vue-best-practices/rules/fallthrough-attributes.md

@@ -0,0 +1,63 @@
+---
+title: Enable Fallthrough Attributes Type Checking
+impact: MEDIUM
+impactDescription: enables IDE autocomplete for fallthrough attributes in wrapper components
+type: capability
+tags: fallthroughAttributes, vueCompilerOptions, component-library, wrapper-components
+---
+
+# Enable Fallthrough Attributes Type Checking
+
+**Impact: MEDIUM** - enables type-aware attribute forwarding in component libraries
+
+When building component libraries with wrapper components, enable `fallthroughAttributes` to get IDE autocomplete for attributes that will be forwarded to child elements.
+
+## What It Does
+
+Wrapper components that pass attributes to child elements can benefit from type-aware completion:
+
+```vue
+<!-- MyButton.vue - wrapper around native button -->
+<template>
+  <button v-bind="$attrs"><slot /></button>
+</template>
+```
+
+## Solution
+
+Enable `fallthroughAttributes` in your tsconfig:
+
+```json
+// tsconfig.json or tsconfig.app.json
+{
+  "vueCompilerOptions": {
+    "fallthroughAttributes": true
+  }
+}
+```
+
+## How It Works
+
+When `fallthroughAttributes: true`:
+- Vue Language Server analyzes which element receives `$attrs`
+- IDE autocomplete suggests valid attributes for the target element
+- Helps developers discover available attributes
+
+> **Note:** This primarily enables IDE autocomplete for valid fallthrough attributes. It does NOT reject invalid attributes as type errors - arbitrary attributes are still allowed.
+
+## Related Options
+
+Combine with `strictTemplates` for comprehensive checking:
+
+```json
+{
+  "vueCompilerOptions": {
+    "strictTemplates": true,
+    "fallthroughAttributes": true
+  }
+}
+```
+
+## Reference
+
+- [Vue Language Tools Wiki - Vue Compiler Options](https://github.com/vuejs/language-tools/wiki/Vue-Compiler-Options)

.agents/skills/vue-best-practices/rules/hmr-vue-ssr.md

@@ -0,0 +1,124 @@
+---
+title: HMR Debugging for Vue SSR
+impact: MEDIUM
+impactDescription: fixes Hot Module Replacement breaking in Vue SSR applications
+type: efficiency
+tags: vite, hmr, ssr, vue, hot-reload, server-side-rendering
+---
+
+# HMR Debugging for Vue SSR
+
+**Impact: MEDIUM** - fixes Hot Module Replacement breaking in Vue SSR applications
+
+Hot Module Replacement breaks when modifying Vue component `<script setup>` sections in SSR applications. Changes cause errors instead of smooth updates, requiring full page reloads.
+
+## Symptoms
+
+- HMR works for `<template>` changes but breaks for `<script setup>`
+- "Cannot read property of undefined" after saving
+- Full page reload required after script changes
+- HMR works in dev:client but not dev:ssr
+
+## Root Cause
+
+SSR mode has a different transformation pipeline. The Vue plugin's HMR boundary detection doesn't handle SSR modules the same way as client modules.
+
+## Fix
+
+**Step 1: Ensure correct SSR plugin configuration**
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+  plugins: [vue()],
+  ssr: {
+    // Don't externalize these for HMR to work
+    noExternal: ['vue', '@vue/runtime-core', '@vue/runtime-dom']
+  }
+})
+```
+
+**Step 2: Configure dev server for SSR HMR**
+```typescript
+// server.ts
+import { createServer } from 'vite'
+
+const vite = await createServer({
+  server: { middlewareMode: true },
+  appType: 'custom'
+})
+
+// Use vite.ssrLoadModule for server-side imports
+const { render } = await vite.ssrLoadModule('/src/entry-server.ts')
+
+// Handle HMR
+vite.watcher.on('change', async (file) => {
+  if (file.endsWith('.vue')) {
+    // Invalidate the module
+    const mod = vite.moduleGraph.getModuleById(file)
+    if (mod) {
+      vite.moduleGraph.invalidateModule(mod)
+    }
+  }
+})
+```
+
+**Step 3: Add HMR acceptance in entry-server**
+```typescript
+// entry-server.ts
+import { createApp } from './main'
+
+export async function render(url: string) {
+  const app = createApp()
+  // ... render logic
+}
+
+// Accept HMR updates
+if (import.meta.hot) {
+  import.meta.hot.accept()
+}
+```
+
+## Framework-Specific Solutions
+
+### Nuxt 3
+HMR should work out of the box. If not:
+```bash
+rm -rf .nuxt node_modules/.vite
+npm install
+npm run dev
+```
+
+### Vite SSR Template
+Ensure you're using the latest `@vitejs/plugin-vue`:
+```bash
+npm install @vitejs/plugin-vue@latest
+```
+
+## Debugging
+
+Enable verbose HMR logging:
+```typescript
+// vite.config.ts
+export default defineConfig({
+  server: {
+    hmr: {
+      overlay: true
+    }
+  },
+  logLevel: 'info'  // Shows HMR updates
+})
+```
+
+## Known Limitations
+
+- HMR for `<script>` (not `<script setup>`) may require full reload
+- SSR components with external dependencies may not hot-reload
+- State is not preserved for SSR components (expected behavior)
+
+## Reference
+
+- [vite-plugin-vue#525](https://github.com/vitejs/vite-plugin-vue/issues/525)
+- [Vite SSR Guide](https://vite.dev/guide/ssr.html)

.agents/skills/vue-best-practices/rules/module-resolution-bundler.md

@@ -0,0 +1,81 @@
+---
+title: moduleResolution Bundler Migration Issues
+impact: HIGH
+impactDescription: fixes "Cannot find module" errors after @vue/tsconfig upgrade
+type: capability
+tags: moduleResolution, bundler, tsconfig, vue-tsconfig, node, esm
+---
+
+# moduleResolution Bundler Migration Issues
+
+**Impact: HIGH** - fixes "Cannot find module" errors after @vue/tsconfig upgrade
+
+Recent versions of `@vue/tsconfig` changed `moduleResolution` from `"node"` to `"bundler"`. This can break existing projects with errors like "Cannot find module 'vue'" or issues with `resolveJsonModule`.
+
+## Symptoms
+
+- `Cannot find module 'vue'` or other packages
+- `Option '--resolveJsonModule' cannot be specified without 'node' module resolution`
+- Errors appear after updating `@vue/tsconfig`
+- Some third-party packages no longer resolve
+
+## Root Cause
+
+`moduleResolution: "bundler"` requires:
+1. TypeScript 5.0+
+2. Packages to have proper `exports` field in package.json
+3. Different resolution rules than Node.js classic resolution
+
+## Fix
+
+**Option 1: Ensure TypeScript 5.0+ everywhere**
+```bash
+npm install -D typescript@^5.0.0
+```
+
+In monorepos, ALL packages must use TypeScript 5.0+.
+
+**Option 2: Add compatibility workaround**
+```json
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolvePackageJsonExports": false
+  }
+}
+```
+
+Setting `resolvePackageJsonExports: false` restores compatibility with packages that don't have proper exports.
+
+**Option 3: Revert to Node resolution**
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "node"
+  }
+}
+```
+
+## Which Packages Break?
+
+Packages break if they:
+- Lack `exports` field in package.json
+- Have incorrect `exports` configuration
+- Rely on Node.js-specific resolution behavior
+
+## Diagnosis
+
+```bash
+# Check which resolution is being used
+cat tsconfig.json | grep moduleResolution
+
+# Test if a specific module resolves
+npx tsc --traceResolution 2>&1 | grep "module-name"
+```
+
+## Reference
+
+- [vuejs/tsconfig#8](https://github.com/vuejs/tsconfig/issues/8)
+- [TypeScript moduleResolution docs](https://www.typescriptlang.org/tsconfig#moduleResolution)
+- [Vite discussion#14001](https://github.com/vitejs/vite/discussions/14001)

.agents/skills/vue-best-practices/rules/pinia-store-mocking.md

@@ -0,0 +1,159 @@
+---
+title: Mocking Pinia Stores with Vitest
+impact: HIGH
+impactDescription: properly mocks Pinia stores in component tests
+type: efficiency
+tags: pinia, vitest, testing, mock, createTestingPinia, store
+---
+
+# Mocking Pinia Stores with Vitest
+
+**Impact: HIGH** - properly mocks Pinia stores in component tests
+
+Developers struggle to properly mock Pinia stores: `createTestingPinia` requires explicit `createSpy` configuration, and "injection Symbol(pinia) not found" errors occur without proper setup.
+
+> **Important (@pinia/testing 1.0+):** The `createSpy` option is **REQUIRED**, not optional. Omitting it throws an error: "You must configure the `createSpy` option."
+
+## Symptoms
+
+- "injection Symbol(pinia) not found" error
+- "You must configure the `createSpy` option" error
+- Actions not properly mocked
+- Store state not reset between tests
+
+## Fix
+
+**Pattern 1: Basic setup with createTestingPinia**
+```typescript
+import { mount } from '@vue/test-utils'
+import { createTestingPinia } from '@pinia/testing'
+import { vi } from 'vitest'
+import MyComponent from './MyComponent.vue'
+import { useCounterStore } from '@/stores/counter'
+
+test('component uses store', async () => {
+  const wrapper = mount(MyComponent, {
+    global: {
+      plugins: [
+        createTestingPinia({
+          createSpy: vi.fn,  // REQUIRED in @pinia/testing 1.0+
+          initialState: {
+            counter: { count: 10 }  // Set initial state
+          }
+        })
+      ]
+    }
+  })
+
+  // Get the store instance AFTER mounting
+  const store = useCounterStore()
+
+  // Actions are automatically stubbed
+  await wrapper.find('button').trigger('click')
+  expect(store.increment).toHaveBeenCalled()
+})
+```
+
+**Pattern 2: Customize action behavior**
+```typescript
+test('component handles async action', async () => {
+  const wrapper = mount(MyComponent, {
+    global: {
+      plugins: [
+        createTestingPinia({
+          createSpy: vi.fn,
+          stubActions: false  // Don't stub, use real actions
+        })
+      ]
+    }
+  })
+
+  const store = useCounterStore()
+
+  // Override specific action
+  store.fetchData = vi.fn().mockResolvedValue({ items: [] })
+
+  await wrapper.find('.load-button').trigger('click')
+  expect(store.fetchData).toHaveBeenCalled()
+})
+```
+
+**Pattern 3: Testing store directly**
+```typescript
+import { setActivePinia, createPinia } from 'pinia'
+import { useCounterStore } from '@/stores/counter'
+
+describe('Counter Store', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+  })
+
+  test('increments count', () => {
+    const store = useCounterStore()
+    expect(store.count).toBe(0)
+
+    store.increment()
+    expect(store.count).toBe(1)
+  })
+})
+```
+
+## Setup Store with Vitest
+
+```typescript
+// stores/counter.ts - Setup store syntax
+export const useCounterStore = defineStore('counter', () => {
+  const count = ref(0)
+  const doubleCount = computed(() => count.value * 2)
+
+  function increment() {
+    count.value++
+  }
+
+  return { count, doubleCount, increment }
+})
+
+// Test file
+test('setup store works', async () => {
+  const pinia = createTestingPinia({
+    createSpy: vi.fn,
+    initialState: {
+      counter: { count: 5 }
+    }
+  })
+
+  const wrapper = mount(MyComponent, {
+    global: { plugins: [pinia] }
+  })
+
+  const store = useCounterStore()
+  expect(store.count).toBe(5)
+  expect(store.doubleCount).toBe(10)
+})
+```
+
+## Reset Between Tests
+
+```typescript
+describe('Store Tests', () => {
+  let pinia: Pinia
+
+  beforeEach(() => {
+    pinia = createTestingPinia({
+      createSpy: vi.fn
+    })
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  test('test 1', () => { /* ... */ })
+  test('test 2', () => { /* ... */ })
+})
+```
+
+## Reference
+
+- [Pinia Testing Guide](https://pinia.vuejs.org/cookbook/testing.html)
+- [Pinia Discussion #2092](https://github.com/vuejs/pinia/discussions/2092)

.agents/skills/vue-best-practices/rules/script-setup-jsdoc.md

@@ -0,0 +1,85 @@
+---
+title: JSDoc Documentation for Script Setup Components
+impact: MEDIUM
+impactDescription: enables proper documentation for composition API components
+type: capability
+tags: jsdoc, script-setup, documentation, composition-api, component
+---
+
+# JSDoc Documentation for Script Setup Components
+
+**Impact: MEDIUM** - enables proper documentation for composition API components
+
+`<script setup>` doesn't have an obvious place to attach JSDoc comments for the component itself. Use a dual-script pattern.
+
+## Problem
+
+**Incorrect:**
+```vue
+<script setup lang="ts">
+/**
+ * This comment doesn't appear in IDE hover or docs
+ * @component
+ */
+import { ref } from 'vue'
+
+const count = ref(0)
+</script>
+```
+
+JSDoc comments inside `<script setup>` don't attach to the component export because there's no explicit export statement.
+
+## Solution
+
+Use both `<script>` and `<script setup>` blocks:
+
+**Correct:**
+```vue
+<script lang="ts">
+/**
+ * A counter component that displays and increments a value.
+ *
+ * @example
+ * ```vue
+ * <Counter :initial="5" @update="handleUpdate" />
+ * ```
+ *
+ * @component
+ */
+export default {}
+</script>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const props = defineProps<{
+  /** Starting value for the counter */
+  initial?: number
+}>()
+
+const emit = defineEmits<{
+  /** Emitted when counter value changes */
+  update: [value: number]
+}>()
+
+const count = ref(props.initial ?? 0)
+</script>
+```
+
+## How It Works
+
+- The regular `<script>` block's default export is merged with `<script setup>`
+- JSDoc on `export default {}` attaches to the component
+- Props and emits JSDoc in `<script setup>` still work normally
+
+## What Gets Documented
+
+| Location | Shows In |
+|----------|----------|
+| `export default {}` JSDoc | Component import hover |
+| `defineProps` JSDoc | Prop hover in templates |
+| `defineEmits` JSDoc | Event handler hover |
+
+## Reference
+
+- [Vue Language Tools Discussion #5932](https://github.com/vuejs/language-tools/discussions/5932)

.agents/skills/vue-best-practices/rules/strict-css-modules.md

@@ -0,0 +1,68 @@
+---
+title: Enable Strict CSS Modules Type Checking
+impact: MEDIUM
+impactDescription: catches typos in CSS module class names at compile time
+type: capability
+tags: strictCssModules, vueCompilerOptions, css-modules, style-module
+---
+
+# Enable Strict CSS Modules Type Checking
+
+**Impact: MEDIUM** - catches typos in CSS module class names at compile time
+
+When using CSS modules with `<style module>`, Vue doesn't validate class names by default. Enable `strictCssModules` to catch typos and undefined classes.
+
+## Problem
+
+CSS module class name errors go undetected:
+
+```vue
+<script setup lang="ts">
+// No error for typo in class name
+</script>
+
+<template>
+  <div :class="$style.buttn">Click me</div>
+</template>
+
+<style module>
+.button {
+  background: blue;
+}
+</style>
+```
+
+The typo `buttn` instead of `button` silently fails at runtime.
+
+## Solution
+
+Enable `strictCssModules` in your tsconfig:
+
+```json
+// tsconfig.json or tsconfig.app.json
+{
+  "vueCompilerOptions": {
+    "strictCssModules": true
+  }
+}
+```
+
+Now `$style.buttn` will show a type error because `buttn` doesn't exist in the CSS module.
+
+## What Gets Checked
+
+| Access | With strictCssModules |
+|--------|----------------------|
+| `$style.validClass` | OK |
+| `$style.typo` | Error: Property 'typo' does not exist |
+| `$style['dynamic']` | OK (dynamic access not checked) |
+
+## Limitations
+
+- Only checks static property access (`$style.className`)
+- Dynamic access (`$style[variable]`) is not validated
+- Only works with `<style module>`, not external CSS files
+
+## Reference
+
+- [Vue Language Tools Wiki - Vue Compiler Options](https://github.com/vuejs/language-tools/wiki/Vue-Compiler-Options)

.agents/skills/vue-best-practices/rules/volar-3-breaking-changes.md

@@ -0,0 +1,65 @@
+---
+title: Volar 3.0 Breaking Changes
+impact: HIGH
+impactDescription: fixes editor integration after Volar/vue-language-server upgrade
+type: capability
+tags: volar, vue-language-server, neovim, vscode, ide, ts_ls, vtsls
+---
+
+# Volar 3.0 Breaking Changes
+
+**Impact: HIGH** - fixes editor integration after Volar/vue-language-server upgrade
+
+Volar 3.0 (vue-language-server 3.x) introduced breaking changes to the language server protocol. Editors configured for Volar 2.x will break with errors like "vue_ls doesn't work with ts_ls.. it expects vtsls".
+
+## Symptoms
+
+- `vue_ls doesn't work with ts_ls`
+- TypeScript features stop working in Vue files
+- No autocomplete, type hints, or error highlighting
+- Editor shows "Language server initialization failed"
+
+## Fix by Editor
+
+### VSCode
+
+Update the "Vue - Official" extension to latest version. It manages the language server automatically.
+
+### NeoVim (nvim-lspconfig)
+
+**Option 1: Use vtsls instead of ts_ls**
+```lua
+-- Replace ts_ls/tsserver with vtsls
+require('lspconfig').vtsls.setup({})
+require('lspconfig').volar.setup({})
+```
+
+**Option 2: Downgrade vue-language-server**
+```bash
+npm install -g @vue/language-server@2.1.10
+```
+
+### JetBrains IDEs
+
+Update to latest Vue plugin. If issues persist, disable and re-enable the Vue plugin.
+
+## What Changed in 3.0
+
+| Feature | Volar 2.x | Volar 3.0 |
+|---------|-----------|-----------|
+| TypeScript integration | ts_ls/tsserver | vtsls recommended (Neovim) |
+| Hybrid mode | Optional | Default |
+
+## Workaround: Stay on 2.x
+
+If upgrading is not possible:
+```bash
+npm install -g @vue/language-server@^2.0.0
+```
+
+Pin in your project's package.json to prevent accidental upgrades.
+
+## Reference
+
+- [vuejs/language-tools#5598](https://github.com/vuejs/language-tools/issues/5598)
+- [NeoVim Vue Setup Guide](https://dev.to/danwalsh/solved-vue-3-typescript-inlay-hint-support-in-neovim-53ej)

.agents/skills/vue-best-practices/rules/vue-directive-comments.md

@@ -0,0 +1,73 @@
+---
+title: Vue Template Directive Comments
+impact: HIGH
+impactDescription: enables fine-grained control over template type checking
+type: capability
+tags: vue-directive, vue-ignore, vue-expect-error, vue-skip, template, type-checking
+---
+
+# Vue Template Directive Comments
+
+**Impact: HIGH** - enables fine-grained control over template type checking
+
+Vue Language Tools supports special directive comments to control type checking behavior in templates.
+
+## Available Directives
+
+### @vue-ignore
+
+Suppress type errors for the next line:
+
+```vue
+<template>
+  <!-- @vue-ignore -->
+  <Component :prop="valueWithTypeError" />
+</template>
+```
+
+### @vue-expect-error
+
+Assert that the next line should have a type error (useful for testing):
+
+```vue
+<template>
+  <!-- @vue-expect-error -->
+  <Component :invalid-prop="value" />
+</template>
+```
+
+### @vue-skip
+
+Skip type checking for an entire block:
+
+```vue
+<template>
+  <!-- @vue-skip -->
+  <div>
+    <!-- Everything in here is not type-checked -->
+    <LegacyComponent :any="props" :go="here" />
+  </div>
+</template>
+```
+
+### @vue-generic
+
+Declare template-level generic types:
+
+```vue
+<template>
+  <!-- @vue-generic {T extends string} -->
+  <GenericList :items="items as T[]" />
+</template>
+```
+
+## Use Cases
+
+- Migrating legacy components with incomplete types
+- Working with third-party components that have incorrect type definitions
+- Temporarily suppressing errors during refactoring
+- Testing that certain patterns produce expected type errors
+
+## Reference
+
+- [Vue Language Tools Wiki - Directive Comments](https://github.com/vuejs/language-tools/wiki/Directive-Comments)

.agents/skills/vue-best-practices/rules/vue-router-typed-params.md

@@ -0,0 +1,81 @@
+---
+title: Vue Router useRoute Params Union Type Narrowing
+impact: MEDIUM
+impactDescription: fixes "Property does not exist" errors with typed route params
+type: capability
+tags: vue-router, useRoute, unplugin-vue-router, typed-routes, params
+---
+
+# Vue Router useRoute Params Union Type Narrowing
+
+**Impact: MEDIUM** - fixes "Property does not exist" errors with typed route params
+
+With `unplugin-vue-router` typed routes, `route.params` becomes a union of ALL page param types. TypeScript cannot narrow `Record<never, never> | { id: string }` properly, causing "Property 'id' does not exist" errors even on the correct page.
+
+## Symptoms
+
+- "Property 'id' does not exist on type 'RouteParams'"
+- `route.params.id` shows as `string | undefined` everywhere
+- Union type of all route params instead of specific route
+- Type narrowing with `if (route.name === 'users-id')` doesn't work
+
+## Root Cause
+
+`unplugin-vue-router` generates a union type of all possible route params. TypeScript's control flow analysis can't narrow this union based on route name checks.
+
+## Fix
+
+**Option 1: Pass route name to useRoute (recommended)**
+```typescript
+// pages/users/[id].vue
+import { useRoute } from 'vue-router/auto'
+
+// Specify the route path for proper typing
+const route = useRoute('/users/[id]')
+
+// Now properly typed as { id: string }
+console.log(route.params.id)  // string, not string | undefined
+```
+
+**Option 2: Type assertion with specific route**
+```typescript
+import { useRoute } from 'vue-router'
+import type { RouteLocationNormalized } from 'vue-router/auto-routes'
+
+const route = useRoute() as RouteLocationNormalized<'/users/[id]'>
+route.params.id  // Properly typed
+```
+
+**Option 3: Define route-specific param type**
+```typescript
+// In your page component
+interface UserRouteParams {
+  id: string
+}
+
+const route = useRoute()
+const { id } = route.params as UserRouteParams
+```
+
+## Required tsconfig Setting
+
+Ensure `moduleResolution: "bundler"` for unplugin-vue-router:
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+## Caveat: Route Name Format
+
+The route name matches the file path pattern:
+- `pages/users/[id].vue` → `/users/[id]`
+- `pages/posts/[slug]/comments.vue` → `/posts/[slug]/comments`
+
+## Reference
+
+- [unplugin-vue-router#337](https://github.com/posva/unplugin-vue-router/issues/337)
+- [unplugin-vue-router#176](https://github.com/posva/unplugin-vue-router/discussions/176)
+- [unplugin-vue-router TypeScript docs](https://uvr.esm.is/guide/typescript.html)

.agents/skills/vue-best-practices/rules/vue-tsc-strict-templates.md

@@ -0,0 +1,69 @@
+---
+title: Enable Strict Template Checking
+impact: HIGH
+impactDescription: catches undefined components and props at compile time
+type: capability
+tags: vue-tsc, typescript, type-checking, templates, vueCompilerOptions
+---
+
+# Enable Strict Template Checking
+
+**Impact: HIGH** - catches undefined components and props at compile time
+
+By default, vue-tsc does not report errors for undefined components in templates. Enable `strictTemplates` to catch these issues during type checking.
+
+## Which tsconfig?
+
+Add `vueCompilerOptions` to the tsconfig that includes Vue source files. In projects with multiple tsconfigs (like those created with `create-vue`), this is typically `tsconfig.app.json`, not the root `tsconfig.json` or `tsconfig.node.json`.
+
+**Incorrect (missing strict checking):**
+
+```json
+{
+  "compilerOptions": {
+    "strict": true
+  }
+  // vueCompilerOptions not configured - undefined components won't error
+}
+```
+
+**Correct (strict template checking enabled):**
+
+```json
+{
+  "compilerOptions": {
+    "strict": true
+  },
+  "vueCompilerOptions": {
+    "strictTemplates": true
+  }
+}
+```
+
+## Available Options
+
+| Option | Default | Effect |
+|--------|---------|--------|
+| `strictTemplates` | `false` | Enables all checkUnknown* options below |
+| `checkUnknownComponents` | `false` | Error on undefined/unregistered components |
+| `checkUnknownProps` | `false` | Error on props not declared in component definition |
+| `checkUnknownEvents` | `false` | Error on events not declared via `defineEmits` |
+| `checkUnknownDirectives` | `false` | Error on unregistered custom directives |
+
+## Granular Control
+
+If `strictTemplates` is too strict, enable individual checks:
+
+```json
+{
+  "vueCompilerOptions": {
+    "checkUnknownComponents": true,
+    "checkUnknownProps": false
+  }
+}
+```
+
+## Reference
+
+- [Vue Compiler Options](https://github.com/vuejs/language-tools/wiki/Vue-Compiler-Options)
+- [Vite Vue+TS Template](https://github.com/vitejs/vite/tree/main/packages/create-vite/template-vue-ts)

.agents/skills/vue-best-practices/rules/with-defaults-union-types.md

@@ -0,0 +1,102 @@
+---
+title: withDefaults Incorrect Default with Union Types
+impact: MEDIUM
+impactDescription: fixes spurious "Missing required prop" warning with union type props
+type: capability
+tags: withDefaults, defineProps, union-types, defaults, vue-3.5
+---
+
+# withDefaults Incorrect Default with Union Types
+
+**Impact: MEDIUM** - fixes spurious "Missing required prop" warning with union type props
+
+Using `withDefaults` with union types like `false | string` may produce a Vue runtime warning "Missing required prop" even when a default is provided. The runtime value IS applied correctly, but the warning can be confusing.
+
+## Symptoms
+
+- Vue warns "Missing required prop" despite default being set
+- Warning appears only with union types like `false | string`
+- TypeScript types are correct
+- Runtime value IS correct (the default is applied)
+
+## Problematic Pattern
+
+```typescript
+// This produces a spurious warning (but works at runtime)
+interface Props {
+  value: false | string  // Union type
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  value: 'default'  // Runtime value IS correct, but Vue warns about missing prop
+})
+```
+
+## Fix
+
+**Option 1: Use Reactive Props Destructure (Vue 3.5+)**
+```vue
+<script setup lang="ts">
+interface Props {
+  value: false | string
+}
+
+// Preferred in Vue 3.5+
+const { value = 'default' } = defineProps<Props>()
+</script>
+```
+
+**Option 2: Use runtime declaration**
+```vue
+<script setup lang="ts">
+const props = defineProps({
+  value: {
+    type: [Boolean, String] as PropType<false | string>,
+    default: 'default'
+  }
+})
+</script>
+```
+
+**Option 3: Split into separate props**
+```typescript
+interface Props {
+  enabled: boolean
+  customValue?: string
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  enabled: false,
+  customValue: 'default'
+})
+```
+
+## Why Reactive Props Destructure Works
+
+Vue 3.5's Reactive Props Destructure handles default values at the destructuring level, bypassing the type inference issues with `withDefaults`.
+
+```typescript
+// The default is applied during destructuring, not type inference
+const { prop = 'default' } = defineProps<{ prop?: string }>()
+```
+
+## Enable Reactive Props Destructure
+
+This is enabled by default in Vue 3.5+. For older versions:
+```javascript
+// vite.config.js
+export default {
+  plugins: [
+    vue({
+      script: {
+        propsDestructure: true
+      }
+    })
+  ]
+}
+```
+
+## Reference
+
+- [vuejs/core#12897](https://github.com/vuejs/core/issues/12897)
+- [Reactive Props Destructure RFC](https://github.com/vuejs/rfcs/discussions/502)

.agents/skills/vue/GENERATION.md

@@ -0,0 +1,5 @@
+# Generation Info
+
+- **Source:** `sources/vue`
+- **Git SHA:** `dcf363038ab2f5b4571028669cf893d084b6b207`
+- **Generated:** 2026-01-28